<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<meta http-equiv="cache-control" content="no-cache">
<title>Genivia - README.md Source File</title>
<link href="genivia_tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="genivia_content.css" rel="stylesheet" type="text/css">
</head>
<body>
<div id="top">
 <div id="titlearea">
  <table height="72px" width="100%" cellspacing="0" cellpadding="0">
   <tbody>
    <tr>
     <td width="10%">&nbsp;</td>
     <td width="175px"><a href="https://www.genivia.com"><img alt="Genivia" src="GeniviaLogo2_trans_noslogan.png"/></a></td>
     <td class="tab_home"><a href="https://www.genivia.com">Home</a></td>
     <td class="tab_home"><a href="https://www.genivia.com/docs.html">Documentation</a></td>
     <td>
      <div style="float: right; font-size: 18px; font-weight: bold;">README.md Source File</div>
      <br>
      <div style="float: right; font-size: 10px;">updated Sun Dec 4 2022 by Robert van Engelen</div>
     </td>
     <td width="10%">&nbsp;</td>
    </tr>
   </tbody>
  </table>
 </div>
<!-- Generated by Doxygen 1.8.11 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="annotated.html"><span>Classes</span></a></li>
      <li class="current"><a href="files.html"><span>Files</span></a></li>
    </ul>
  </div>
  <div id="navrow2" class="tabs2">
    <ul class="tablist">
      <li><a href="files.html"><span>File&#160;List</span></a></li>
      <li><a href="globals.html"><span>File&#160;Members</span></a></li>
    </ul>
  </div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('_r_e_a_d_m_e_8md.html','');});
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">README.md</div>  </div>
</div><!--header-->
<div class="contents">
<a href="_r_e_a_d_m_e_8md.html">Go to the documentation of this file.</a><div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno">    1</span>&#160;</div><div class="line"><a name="l00002"></a><span class="lineno">    2</span>&#160;C and C++ XML Data Bindings                                          {#mainpage}</div><div class="line"><a name="l00003"></a><span class="lineno">    3</span>&#160;===========================</div><div class="line"><a name="l00004"></a><span class="lineno">    4</span>&#160;</div><div class="line"><a name="l00005"></a><span class="lineno">    5</span>&#160;[TOC]</div><div class="line"><a name="l00006"></a><span class="lineno">    6</span>&#160;</div><div class="line"><a name="l00007"></a><span class="lineno">    7</span>&#160;Introduction                                                            {#intro}</div><div class="line"><a name="l00008"></a><span class="lineno">    8</span>&#160;============</div><div class="line"><a name="l00009"></a><span class="lineno">    9</span>&#160;</div><div class="line"><a name="l00010"></a><span class="lineno">   10</span>&#160;This article presents a detailed overview of the gSOAP XML data bindings for C</div><div class="line"><a name="l00011"></a><span class="lineno">   11</span>&#160;and C++.  The XML data bindings for C and C++ are extensively used with gSOAP</div><div class="line"><a name="l00012"></a><span class="lineno">   12</span>&#160;Web services to serialize C and C++ data in XML as part of the SOAP/XML Web</div><div class="line"><a name="l00013"></a><span class="lineno">   13</span>&#160;services payloads.  Also REST XML with gSOAP relies on XML serialization of C</div><div class="line"><a name="l00014"></a><span class="lineno">   14</span>&#160;and C++ data via XML data bindings.</div><div class="line"><a name="l00015"></a><span class="lineno">   15</span>&#160;</div><div class="line"><a name="l00016"></a><span class="lineno">   16</span>&#160;The major advantage of XML data bindings is that your application data is</div><div class="line"><a name="l00017"></a><span class="lineno">   17</span>&#160;always **type safe** in C and C++ by binding XML schema types to C/C++ types.</div><div class="line"><a name="l00018"></a><span class="lineno">   18</span>&#160;So integers in XML are bound to C integers, strings in XML are bound to C or</div><div class="line"><a name="l00019"></a><span class="lineno">   19</span>&#160;C++ strings, complex types in XML are bound to C structs or C++ classes, and so</div><div class="line"><a name="l00020"></a><span class="lineno">   20</span>&#160;on.  The structured data you create and accept will fit the data model and is</div><div class="line"><a name="l00021"></a><span class="lineno">   21</span>&#160;**static type safe**.  In other words, by leveraging strong typing in C/C++,</div><div class="line"><a name="l00022"></a><span class="lineno">   22</span>&#160;your XML data meets **XML schema validation requirements** and satisfies **XML</div><div class="line"><a name="l00023"></a><span class="lineno">   23</span>&#160;interoperability requirements**.</div><div class="line"><a name="l00024"></a><span class="lineno">   24</span>&#160;</div><div class="line"><a name="l00025"></a><span class="lineno">   25</span>&#160;In fact, gSOAP data bindings are more powerful than simply representing C/C++</div><div class="line"><a name="l00026"></a><span class="lineno">   26</span>&#160;data in XML.  The gSOAP tools implement true and tested **structure-preserving</div><div class="line"><a name="l00027"></a><span class="lineno">   27</span>&#160;serialization** of C/C++ data in XML, including the serialization of cyclic</div><div class="line"><a name="l00028"></a><span class="lineno">   28</span>&#160;graph structures with id-ref XML attributes.  The gSOAP tools also generate</div><div class="line"><a name="l00029"></a><span class="lineno">   29</span>&#160;routines for deep copying and deep deletion of C/C++ data structures to</div><div class="line"><a name="l00030"></a><span class="lineno">   30</span>&#160;simplify memory management.  In addition, C/C++ structures are deserialized</div><div class="line"><a name="l00031"></a><span class="lineno">   31</span>&#160;into managed memory, managed by the gSOAP `soap` context.</div><div class="line"><a name="l00032"></a><span class="lineno">   32</span>&#160;</div><div class="line"><a name="l00033"></a><span class="lineno">   33</span>&#160;At the end of this article two examples are given to illustrate the application</div><div class="line"><a name="l00034"></a><span class="lineno">   34</span>&#160;of XML data bindings.  The first simple example &lt;i&gt;`address.cpp`&lt;/i&gt; shows how to use</div><div class="line"><a name="l00035"></a><span class="lineno">   35</span>&#160;wsdl2h to bind an XML schema to C++.  The C++ application reads and writes an</div><div class="line"><a name="l00036"></a><span class="lineno">   36</span>&#160;XML file into and from a C++ &quot;address book&quot; data structure as a simple example.</div><div class="line"><a name="l00037"></a><span class="lineno">   37</span>&#160;The C++ data structure is an STL vector of address objects.  The second example</div><div class="line"><a name="l00038"></a><span class="lineno">   38</span>&#160;&lt;i&gt;`graph.cpp`&lt;/i&gt; shows how C++ data can be accurately serialized as a tree, digraph,</div><div class="line"><a name="l00039"></a><span class="lineno">   39</span>&#160;and cyclic graph in XML.  The digraph and cyclic graph serialization rules</div><div class="line"><a name="l00040"></a><span class="lineno">   40</span>&#160;implement SOAP 1.1/1.2 multi-ref encoding with id-ref attributes to link</div><div class="line"><a name="l00041"></a><span class="lineno">   41</span>&#160;elements through IDREF XML references, creating a an XML graph with pointers to</div><div class="line"><a name="l00042"></a><span class="lineno">   42</span>&#160;XML nodes that preserves the structural integrity of the serialized C++ data.</div><div class="line"><a name="l00043"></a><span class="lineno">   43</span>&#160;</div><div class="line"><a name="l00044"></a><span class="lineno">   44</span>&#160;These examples demonstrate XML data bindings only for relatively simple data</div><div class="line"><a name="l00045"></a><span class="lineno">   45</span>&#160;structures and types.  The gSOAP tools support more than just these type of</div><div class="line"><a name="l00046"></a><span class="lineno">   46</span>&#160;structures to serialize in XML.  There are practically no limits to the</div><div class="line"><a name="l00047"></a><span class="lineno">   47</span>&#160;serialization of C and C++ data types in XML.</div><div class="line"><a name="l00048"></a><span class="lineno">   48</span>&#160;</div><div class="line"><a name="l00049"></a><span class="lineno">   49</span>&#160;Also the support for XML schema (XSD) components is unlimited.  The wsdl2h tool</div><div class="line"><a name="l00050"></a><span class="lineno">   50</span>&#160;maps schemas to C and C++ using built-in intuitive mapping rules, while</div><div class="line"><a name="l00051"></a><span class="lineno">   51</span>&#160;allowing the mappings to be customized using a &lt;i&gt;`typemap.dat`&lt;/i&gt; file with mapping</div><div class="line"><a name="l00052"></a><span class="lineno">   52</span>&#160;instructions for wsdl2h.</div><div class="line"><a name="l00053"></a><span class="lineno">   53</span>&#160;</div><div class="line"><a name="l00054"></a><span class="lineno">   54</span>&#160;The information in this article is applicable to gSOAP 2.8.26 and greater that</div><div class="line"><a name="l00055"></a><span class="lineno">   55</span>&#160;support C++11 features.  However, C++11 is not required.  The material and the</div><div class="line"><a name="l00056"></a><span class="lineno">   56</span>&#160;examples in this article use plain C and C++, until the point where we</div><div class="line"><a name="l00057"></a><span class="lineno">   57</span>&#160;introduce C++11 smart pointers and scoped enumerations.  While most of the</div><div class="line"><a name="l00058"></a><span class="lineno">   58</span>&#160;examples in this article are given in C++, the concepts also apply to C with</div><div class="line"><a name="l00059"></a><span class="lineno">   59</span>&#160;the exception of containers, smart pointers, classes and their methods.  None</div><div class="line"><a name="l00060"></a><span class="lineno">   60</span>&#160;of these exceptions limit the use of the gSOAP tools for C in any way.</div><div class="line"><a name="l00061"></a><span class="lineno">   61</span>&#160;</div><div class="line"><a name="l00062"></a><span class="lineno">   62</span>&#160;The data binding concepts described in this article were first envisioned in</div><div class="line"><a name="l00063"></a><span class="lineno">   63</span>&#160;1999 by Prof. Robert van Engelen at the Florida State University.  An</div><div class="line"><a name="l00064"></a><span class="lineno">   64</span>&#160;implementation was created in 2000, named &quot;stub/skeleton compiler&quot;.  The first</div><div class="line"><a name="l00065"></a><span class="lineno">   65</span>&#160;articles on its successor version &quot;gSOAP&quot; appeared in 2002.  The principle of</div><div class="line"><a name="l00066"></a><span class="lineno">   66</span>&#160;mapping XSD components to C/C++ types and vice versa is now widely adopted in</div><div class="line"><a name="l00067"></a><span class="lineno">   67</span>&#160;systems and programming languages, including Java web services and by C# WCF.</div><div class="line"><a name="l00068"></a><span class="lineno">   68</span>&#160;</div><div class="line"><a name="l00069"></a><span class="lineno">   69</span>&#160;We continue to be committed to our goal to empower C/C++ developers with</div><div class="line"><a name="l00070"></a><span class="lineno">   70</span>&#160;powerful autocoding tools for XML.  Our commitment started in the very early</div><div class="line"><a name="l00071"></a><span class="lineno">   71</span>&#160;days of SOAP by actively participating in</div><div class="line"><a name="l00072"></a><span class="lineno">   72</span>&#160;[SOAP interoperability testing](http://www.whitemesa.com/interop.htm),</div><div class="line"><a name="l00073"></a><span class="lineno">   73</span>&#160;participating in the development and testing of the</div><div class="line"><a name="l00074"></a><span class="lineno">   74</span>&#160;[W3C XML Schema Patterns for Databinding Interoperability](http://www.w3.org/2002/ws/databinding),</div><div class="line"><a name="l00075"></a><span class="lineno">   75</span>&#160;and continues by contributing to the development of</div><div class="line"><a name="l00076"></a><span class="lineno">   76</span>&#160;[OASIS open standards](https://www.oasis-open.org) in partnership with leading</div><div class="line"><a name="l00077"></a><span class="lineno">   77</span>&#160;IT companies in the world.</div><div class="line"><a name="l00078"></a><span class="lineno">   78</span>&#160;</div><div class="line"><a name="l00079"></a><span class="lineno">   79</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00080"></a><span class="lineno">   80</span>&#160;</div><div class="line"><a name="l00081"></a><span class="lineno">   81</span>&#160;Notational Conventions                                            {#conventions}</div><div class="line"><a name="l00082"></a><span class="lineno">   82</span>&#160;======================</div><div class="line"><a name="l00083"></a><span class="lineno">   83</span>&#160;</div><div class="line"><a name="l00084"></a><span class="lineno">   84</span>&#160;The typographical conventions used by this document are:</div><div class="line"><a name="l00085"></a><span class="lineno">   85</span>&#160;</div><div class="line"><a name="l00086"></a><span class="lineno">   86</span>&#160;* `Courier` denotes C and C++ source code.</div><div class="line"><a name="l00087"></a><span class="lineno">   87</span>&#160;</div><div class="line"><a name="l00088"></a><span class="lineno">   88</span>&#160;* &lt;i&gt;`Courier`&lt;/i&gt; denotes XML content, JSON content, file and path names, and URIs.</div><div class="line"><a name="l00089"></a><span class="lineno">   89</span>&#160;</div><div class="line"><a name="l00090"></a><span class="lineno">   90</span>&#160;* &lt;b&gt;`Courier`&lt;/b&gt; denotes HTTP content, text file content, and shell commands with command line options and arguments.</div><div class="line"><a name="l00091"></a><span class="lineno">   91</span>&#160;</div><div class="line"><a name="l00092"></a><span class="lineno">   92</span>&#160;The keywords &quot;MUST&quot;, &quot;MUST NOT&quot;, &quot;REQUIRED&quot;, &quot;SHALL&quot;, &quot;SHALL NOT&quot;, &quot;SHOULD&quot;,</div><div class="line"><a name="l00093"></a><span class="lineno">   93</span>&#160;&quot;SHOULD NOT&quot;, &quot;RECOMMENDED&quot;, &quot;MAY&quot;, and &quot;OPTIONAL&quot; in this document are to</div><div class="line"><a name="l00094"></a><span class="lineno">   94</span>&#160;be interpreted as described in RFC-2119.</div><div class="line"><a name="l00095"></a><span class="lineno">   95</span>&#160;</div><div class="line"><a name="l00096"></a><span class="lineno">   96</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00097"></a><span class="lineno">   97</span>&#160;</div><div class="line"><a name="l00098"></a><span class="lineno">   98</span>&#160;Mapping WSDL and XML schemas to C/C++                                   {#tocpp}</div><div class="line"><a name="l00099"></a><span class="lineno">   99</span>&#160;=====================================</div><div class="line"><a name="l00100"></a><span class="lineno">  100</span>&#160;</div><div class="line"><a name="l00101"></a><span class="lineno">  101</span>&#160;To convert WSDL and XML schemas (XSD files) to code, we use the wsdl2h command</div><div class="line"><a name="l00102"></a><span class="lineno">  102</span>&#160;on the command line (or command prompt), after opening a terminal.  The wsdl2h</div><div class="line"><a name="l00103"></a><span class="lineno">  103</span>&#160;command generates the data binding interface code that is saved to a special</div><div class="line"><a name="l00104"></a><span class="lineno">  104</span>&#160;Web services and data bindings interface header file with extension &lt;i&gt;`.h`&lt;/i&gt;</div><div class="line"><a name="l00105"></a><span class="lineno">  105</span>&#160;that contains the WSDL service declarations and the data binding interface</div><div class="line"><a name="l00106"></a><span class="lineno">  106</span>&#160;declarations in a familiar C/C++ format:</div><div class="line"><a name="l00107"></a><span class="lineno">  107</span>&#160;</div><div class="line"><a name="l00108"></a><span class="lineno">  108</span>&#160;    wsdl2h [options] -o file.h ... XSD and WSDL files ...</div><div class="line"><a name="l00109"></a><span class="lineno">  109</span>&#160;</div><div class="line"><a name="l00110"></a><span class="lineno">  110</span>&#160;This command converts WSDL and XSD files to C++ (or pure C with</div><div class="line"><a name="l00111"></a><span class="lineno">  111</span>&#160;&lt;b&gt;`wsdl2h -c`&lt;/b&gt;) and saves the data binding interface to a interface header</div><div class="line"><a name="l00112"></a><span class="lineno">  112</span>&#160;file &lt;i&gt;`file.h`&lt;/i&gt; that uses familiar C/C++ syntax extended with `//gsoap`</div><div class="line"><a name="l00113"></a><span class="lineno">  113</span>&#160;[directives](#directives) and annotations.  Notational conventions are used in</div><div class="line"><a name="l00114"></a><span class="lineno">  114</span>&#160;the data binding interface to declare serializable C/C++ types and functions</div><div class="line"><a name="l00115"></a><span class="lineno">  115</span>&#160;for Web service operations.</div><div class="line"><a name="l00116"></a><span class="lineno">  116</span>&#160;</div><div class="line"><a name="l00117"></a><span class="lineno">  117</span>&#160;The WSDL 1.1/2.0, SOAP 1.1/1.2, and XSD 1.0/1.1 standards are supported by the</div><div class="line"><a name="l00118"></a><span class="lineno">  118</span>&#160;gSOAP tools.  In addition, the most popular WS specifications are also</div><div class="line"><a name="l00119"></a><span class="lineno">  119</span>&#160;supported, including WS-Addressing, WS-ReliableMessaging, WS-Discovery,</div><div class="line"><a name="l00120"></a><span class="lineno">  120</span>&#160;WS-Security, WS-Policy, WS-SecurityPolicy, and WS-SecureConversation.</div><div class="line"><a name="l00121"></a><span class="lineno">  121</span>&#160;</div><div class="line"><a name="l00122"></a><span class="lineno">  122</span>&#160;This article focusses mainly on XML data bindings.  XML data bindings for C/C++</div><div class="line"><a name="l00123"></a><span class="lineno">  123</span>&#160;bind XML schema types to C/C++ types.  So integers in XML are bound to C</div><div class="line"><a name="l00124"></a><span class="lineno">  124</span>&#160;integers, strings in XML are bound to C or C++ strings, complex types in XML</div><div class="line"><a name="l00125"></a><span class="lineno">  125</span>&#160;are bound to C structs or C++ classes, and so on.</div><div class="line"><a name="l00126"></a><span class="lineno">  126</span>&#160;</div><div class="line"><a name="l00127"></a><span class="lineno">  127</span>&#160;A data binding is dual, meaning supporting a two way direction for development.</div><div class="line"><a name="l00128"></a><span class="lineno">  128</span>&#160;Either you start with WSDLs and/or XML schemas that are mapped to equivalent</div><div class="line"><a name="l00129"></a><span class="lineno">  129</span>&#160;C/C++ types, or you start with C/C++ types that are mapped to XSD types.</div><div class="line"><a name="l00130"></a><span class="lineno">  130</span>&#160;Either way, the end result is that you can serialize C/C++ types in XML such</div><div class="line"><a name="l00131"></a><span class="lineno">  131</span>&#160;that your XML is an instance of XML schema(s) and is validated against these</div><div class="line"><a name="l00132"></a><span class="lineno">  132</span>&#160;schema(s).</div><div class="line"><a name="l00133"></a><span class="lineno">  133</span>&#160;</div><div class="line"><a name="l00134"></a><span class="lineno">  134</span>&#160;This covers all of the following standard XSD components with their optional</div><div class="line"><a name="l00135"></a><span class="lineno">  135</span>&#160;attributes and properties:</div><div class="line"><a name="l00136"></a><span class="lineno">  136</span>&#160;</div><div class="line"><a name="l00137"></a><span class="lineno">  137</span>&#160;XSD component  | attributes and properties</div><div class="line"><a name="l00138"></a><span class="lineno">  138</span>&#160;-------------- | -------------------------</div><div class="line"><a name="l00139"></a><span class="lineno">  139</span>&#160;schema         | targetNamespace, version, elementFormDefault, attributeFormDefault, defaultAttributes</div><div class="line"><a name="l00140"></a><span class="lineno">  140</span>&#160;attribute      | name, ref, type, use, default, fixed, form, targetNamespace, wsdl:arrayType</div><div class="line"><a name="l00141"></a><span class="lineno">  141</span>&#160;element        | name, ref, type, default, fixed, form, nillable, abstract, substitutionGroup, minOccurs, maxOccurs, targetNamespace</div><div class="line"><a name="l00142"></a><span class="lineno">  142</span>&#160;simpleType     | name</div><div class="line"><a name="l00143"></a><span class="lineno">  143</span>&#160;complexType    | name, abstract, mixed, defaultAttributesApply</div><div class="line"><a name="l00144"></a><span class="lineno">  144</span>&#160;all            | *n/a*</div><div class="line"><a name="l00145"></a><span class="lineno">  145</span>&#160;choice         | minOccurs, maxOccurs</div><div class="line"><a name="l00146"></a><span class="lineno">  146</span>&#160;sequence       | minOccurs, maxOccurs</div><div class="line"><a name="l00147"></a><span class="lineno">  147</span>&#160;group          | name, ref, minOccurs, maxOccurs</div><div class="line"><a name="l00148"></a><span class="lineno">  148</span>&#160;attributeGroup | name, ref</div><div class="line"><a name="l00149"></a><span class="lineno">  149</span>&#160;any            | minOccurs, maxOccurs</div><div class="line"><a name="l00150"></a><span class="lineno">  150</span>&#160;anyAttribute   | *n/a*</div><div class="line"><a name="l00151"></a><span class="lineno">  151</span>&#160;</div><div class="line"><a name="l00152"></a><span class="lineno">  152</span>&#160;And also the following standard XSD directives are covered:</div><div class="line"><a name="l00153"></a><span class="lineno">  153</span>&#160;</div><div class="line"><a name="l00154"></a><span class="lineno">  154</span>&#160;directive  | description</div><div class="line"><a name="l00155"></a><span class="lineno">  155</span>&#160;---------- | -----------</div><div class="line"><a name="l00156"></a><span class="lineno">  156</span>&#160;import     | Imports a schema into the importing schema for referencing</div><div class="line"><a name="l00157"></a><span class="lineno">  157</span>&#160;include    | Include schema component definitions into a schema</div><div class="line"><a name="l00158"></a><span class="lineno">  158</span>&#160;override   | Override by replacing schema component definitions</div><div class="line"><a name="l00159"></a><span class="lineno">  159</span>&#160;redefine   | Extend or restrict schema component definitions</div><div class="line"><a name="l00160"></a><span class="lineno">  160</span>&#160;annotation | Annotates a component</div><div class="line"><a name="l00161"></a><span class="lineno">  161</span>&#160;</div><div class="line"><a name="l00162"></a><span class="lineno">  162</span>&#160;The XSD facets and their mappings to C/C++ are:</div><div class="line"><a name="l00163"></a><span class="lineno">  163</span>&#160;</div><div class="line"><a name="l00164"></a><span class="lineno">  164</span>&#160;XSD facet      | maps to</div><div class="line"><a name="l00165"></a><span class="lineno">  165</span>&#160;-------------- | -------</div><div class="line"><a name="l00166"></a><span class="lineno">  166</span>&#160;enumeration    | `enum`</div><div class="line"><a name="l00167"></a><span class="lineno">  167</span>&#160;simpleContent  | class/struct wrapper with `__item` member</div><div class="line"><a name="l00168"></a><span class="lineno">  168</span>&#160;complexContent | class/struct</div><div class="line"><a name="l00169"></a><span class="lineno">  169</span>&#160;list           | `enum*` bitmask (`enum*` enumerates a bitmask up to 64 bits)</div><div class="line"><a name="l00170"></a><span class="lineno">  170</span>&#160;extension      | class/struct inheritance/extension</div><div class="line"><a name="l00171"></a><span class="lineno">  171</span>&#160;restriction    | `typedef` and class/struct inheritance/redeclaration</div><div class="line"><a name="l00172"></a><span class="lineno">  172</span>&#160;length         | `typedef` with restricted content length annotation</div><div class="line"><a name="l00173"></a><span class="lineno">  173</span>&#160;minLength      | `typedef` with restricted content length annotation</div><div class="line"><a name="l00174"></a><span class="lineno">  174</span>&#160;maxLength      | `typedef` with restricted content length annotation</div><div class="line"><a name="l00175"></a><span class="lineno">  175</span>&#160;minInclusive   | `typedef` with numerical value range restriction annotation</div><div class="line"><a name="l00176"></a><span class="lineno">  176</span>&#160;maxInclusive   | `typedef` with numerical value range restriction annotation</div><div class="line"><a name="l00177"></a><span class="lineno">  177</span>&#160;minExclusive   | `typedef` with numerical value range restriction annotation</div><div class="line"><a name="l00178"></a><span class="lineno">  178</span>&#160;maxExclusive   | `typedef` with numerical value range restriction annotation</div><div class="line"><a name="l00179"></a><span class="lineno">  179</span>&#160;precision      | `typedef` with pattern annotation (pattern used for output, but input is not validated)</div><div class="line"><a name="l00180"></a><span class="lineno">  180</span>&#160;scale          | `typedef` with pattern annotation (pattern used for output, but input is not validated)</div><div class="line"><a name="l00181"></a><span class="lineno">  181</span>&#160;totalDigits    | `typedef` with pattern annotation (pattern used for output, but input is not validated)</div><div class="line"><a name="l00182"></a><span class="lineno">  182</span>&#160;fractionDigits | `typedef` with pattern annotation (pattern used for output, but input is not validated)</div><div class="line"><a name="l00183"></a><span class="lineno">  183</span>&#160;pattern        | `typedef` with pattern annotation (define `soap::fsvalidate` callback to validate patterns)</div><div class="line"><a name="l00184"></a><span class="lineno">  184</span>&#160;union          | string with union of value</div><div class="line"><a name="l00185"></a><span class="lineno">  185</span>&#160;</div><div class="line"><a name="l00186"></a><span class="lineno">  186</span>&#160;All primitive XSD types are supported, including but not limited to the</div><div class="line"><a name="l00187"></a><span class="lineno">  187</span>&#160;following XSD types:</div><div class="line"><a name="l00188"></a><span class="lineno">  188</span>&#160;</div><div class="line"><a name="l00189"></a><span class="lineno">  189</span>&#160;XSD type         | maps to</div><div class="line"><a name="l00190"></a><span class="lineno">  190</span>&#160;---------------- | -------</div><div class="line"><a name="l00191"></a><span class="lineno">  191</span>&#160;any/anyType      | `_XML` string with literal XML content (or enable DOM with wsdl2h option `-d`)</div><div class="line"><a name="l00192"></a><span class="lineno">  192</span>&#160;anyURI           | string (i.e. `char*`, `wchar_t*`, `std::string`, `std::wstring`)</div><div class="line"><a name="l00193"></a><span class="lineno">  193</span>&#160;string           | string (i.e. `char*`, `wchar_t*`, `std::string`, `std::wstring`)</div><div class="line"><a name="l00194"></a><span class="lineno">  194</span>&#160;boolean          | `bool` (C++) or `enum xsd__boolean` (C)</div><div class="line"><a name="l00195"></a><span class="lineno">  195</span>&#160;byte             | `char` (i.e. `int8_t`)</div><div class="line"><a name="l00196"></a><span class="lineno">  196</span>&#160;short            | `short` (i.e. `int16_t`)</div><div class="line"><a name="l00197"></a><span class="lineno">  197</span>&#160;int              | `int` (i.e. `int32_t`)</div><div class="line"><a name="l00198"></a><span class="lineno">  198</span>&#160;long             | `LONG64` (i.e. `long long` and `int64_t`)</div><div class="line"><a name="l00199"></a><span class="lineno">  199</span>&#160;unsignedByte     | `unsigned char` (i.e. `uint8_t`)</div><div class="line"><a name="l00200"></a><span class="lineno">  200</span>&#160;unsignedShort    | `unsigned short` (i.e. `uint16_t`)</div><div class="line"><a name="l00201"></a><span class="lineno">  201</span>&#160;unsignedInt      | `unsigned int` (i.e. `uint32_t`)</div><div class="line"><a name="l00202"></a><span class="lineno">  202</span>&#160;unsignedLong     | `ULONG64` (i.e. `unsigned long long` and `uint64_t`)</div><div class="line"><a name="l00203"></a><span class="lineno">  203</span>&#160;float            | `float`</div><div class="line"><a name="l00204"></a><span class="lineno">  204</span>&#160;double           | `double`</div><div class="line"><a name="l00205"></a><span class="lineno">  205</span>&#160;integer          | string or `#import &quot;custom/int128.h&quot;` to use 128 bit `xsd__integer`</div><div class="line"><a name="l00206"></a><span class="lineno">  206</span>&#160;decimal          | string or `#import &quot;custom/long_double.h&quot;` to use `long double`</div><div class="line"><a name="l00207"></a><span class="lineno">  207</span>&#160;precisionDecimal | string</div><div class="line"><a name="l00208"></a><span class="lineno">  208</span>&#160;duration         | string or `#import &quot;custom/duration.h&quot;` to use 64 bit `xsd__duration`</div><div class="line"><a name="l00209"></a><span class="lineno">  209</span>&#160;dateTime         | `time_t` or `#import &quot;custom/struct_tm.h&quot;` to use `struct tm` for `xsd__dateTime`</div><div class="line"><a name="l00210"></a><span class="lineno">  210</span>&#160;time             | string or `#import &quot;custom/long_time.h&quot;` to use 64 bit `xsd__time`</div><div class="line"><a name="l00211"></a><span class="lineno">  211</span>&#160;date             | string or `#import &quot;custom/struct_tm_date.h&quot;` to use `struct tm` for `xsd__date`</div><div class="line"><a name="l00212"></a><span class="lineno">  212</span>&#160;hexBinary        | special class/struct `xsd__hexBinary`</div><div class="line"><a name="l00213"></a><span class="lineno">  213</span>&#160;base64Binary     | special class/struct `xsd__base64Binary`</div><div class="line"><a name="l00214"></a><span class="lineno">  214</span>&#160;QName            | `_QName` string (URI normalization rules are applied)</div><div class="line"><a name="l00215"></a><span class="lineno">  215</span>&#160;</div><div class="line"><a name="l00216"></a><span class="lineno">  216</span>&#160;All other primitive XSD types not listed above are mapped to strings, by</div><div class="line"><a name="l00217"></a><span class="lineno">  217</span>&#160;wsdl2h generating a `typedef` to string for these types.  For example,</div><div class="line"><a name="l00218"></a><span class="lineno">  218</span>&#160;&lt;i&gt;`xsd:token`&lt;/i&gt; is bound to a C++ or C string:</div><div class="line"><a name="l00219"></a><span class="lineno">  219</span>&#160;</div><div class="line"><a name="l00220"></a><span class="lineno">  220</span>&#160;~~~{.cpp}</div><div class="line"><a name="l00221"></a><span class="lineno">  221</span>&#160;    typedef std::string  xsd__token; // C++</div><div class="line"><a name="l00222"></a><span class="lineno">  222</span>&#160;    typedef char        *xsd__token; // C (wsdl2h option -c)</div><div class="line"><a name="l00223"></a><span class="lineno">  223</span>&#160;~~~</div><div class="line"><a name="l00224"></a><span class="lineno">  224</span>&#160;</div><div class="line"><a name="l00225"></a><span class="lineno">  225</span>&#160;This associates a compatible value space to the type with the appropriate XSD</div><div class="line"><a name="l00226"></a><span class="lineno">  226</span>&#160;type name used by the soapcpp2-generated serializers.</div><div class="line"><a name="l00227"></a><span class="lineno">  227</span>&#160;</div><div class="line"><a name="l00228"></a><span class="lineno">  228</span>&#160;It is possible to remap types by adding the appropriate mapping rules to</div><div class="line"><a name="l00229"></a><span class="lineno">  229</span>&#160;&lt;i&gt;`typemap.dat`&lt;/i&gt; as we will explain in more detail in the next section.</div><div class="line"><a name="l00230"></a><span class="lineno">  230</span>&#160;</div><div class="line"><a name="l00231"></a><span class="lineno">  231</span>&#160;Imported custom serializers are intended to extend the C/C++ type bindings when</div><div class="line"><a name="l00232"></a><span class="lineno">  232</span>&#160;the default binding to string is not satisfactory to your taste and if the</div><div class="line"><a name="l00233"></a><span class="lineno">  233</span>&#160;target platform supports these C/C++ types.  To add custom serializers to</div><div class="line"><a name="l00234"></a><span class="lineno">  234</span>&#160;&lt;i&gt;`typemap.dat`&lt;/i&gt; for wsdl2h, see [adding custom serializers](#custom) below.</div><div class="line"><a name="l00235"></a><span class="lineno">  235</span>&#160;</div><div class="line"><a name="l00236"></a><span class="lineno">  236</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00237"></a><span class="lineno">  237</span>&#160;</div><div class="line"><a name="l00238"></a><span class="lineno">  238</span>&#160;Using typemap.dat to customize data bindings                          {#typemap}</div><div class="line"><a name="l00239"></a><span class="lineno">  239</span>&#160;============================================</div><div class="line"><a name="l00240"></a><span class="lineno">  240</span>&#160;</div><div class="line"><a name="l00241"></a><span class="lineno">  241</span>&#160;Use a &lt;i&gt;`typemap.dat`&lt;/i&gt; file to redefine namespace prefixes and to customize type</div><div class="line"><a name="l00242"></a><span class="lineno">  242</span>&#160;bindings for the the generated header files produced by the wsdl2h tool.  The</div><div class="line"><a name="l00243"></a><span class="lineno">  243</span>&#160;&lt;i&gt;`typemap.dat`&lt;/i&gt; is the default file processed by wsdl2h.  Use &lt;b&gt;`wsdl2h -tfile.dat`&lt;/b&gt;</div><div class="line"><a name="l00244"></a><span class="lineno">  244</span>&#160;option &lt;b&gt;`-tfile.dat`&lt;/b&gt; to specify a different mapping file &lt;i&gt;`file.dat`&lt;/i&gt;.</div><div class="line"><a name="l00245"></a><span class="lineno">  245</span>&#160;</div><div class="line"><a name="l00246"></a><span class="lineno">  246</span>&#160;Declarations in &lt;i&gt;`typemap.dat`&lt;/i&gt; can be broken up over multiple lines by</div><div class="line"><a name="l00247"></a><span class="lineno">  247</span>&#160;continuing on the next line by ending each line to be continued with a</div><div class="line"><a name="l00248"></a><span class="lineno">  248</span>&#160;backslash &lt;b&gt;`\`&lt;/b&gt;.  The limit is 4095 characters per line, whether the line is</div><div class="line"><a name="l00249"></a><span class="lineno">  249</span>&#160;broken up or not.</div><div class="line"><a name="l00250"></a><span class="lineno">  250</span>&#160;</div><div class="line"><a name="l00251"></a><span class="lineno">  251</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00252"></a><span class="lineno">  252</span>&#160;</div><div class="line"><a name="l00253"></a><span class="lineno">  253</span>&#160;XML namespace bindings                                               {#typemap1}</div><div class="line"><a name="l00254"></a><span class="lineno">  254</span>&#160;----------------------</div><div class="line"><a name="l00255"></a><span class="lineno">  255</span>&#160;</div><div class="line"><a name="l00256"></a><span class="lineno">  256</span>&#160;The wsdl2h tool generates C/C++ type declarations that use `ns1`, `ns2`, etc.</div><div class="line"><a name="l00257"></a><span class="lineno">  257</span>&#160;as schema-binding URI prefixes.  These default prefixes are generated somewhat</div><div class="line"><a name="l00258"></a><span class="lineno">  258</span>&#160;arbitrarily for each schema targetNamespace URI, meaning that their ordering</div><div class="line"><a name="l00259"></a><span class="lineno">  259</span>&#160;may change depending on the WSDL and XSD order of processing with wsdl2h.</div><div class="line"><a name="l00260"></a><span class="lineno">  260</span>&#160;</div><div class="line"><a name="l00261"></a><span class="lineno">  261</span>&#160;Therefore, it is **strongly recommended** to declare your own prefix for each</div><div class="line"><a name="l00262"></a><span class="lineno">  262</span>&#160;schema URI in &lt;i&gt;`typemap.dat`&lt;/i&gt; to reduce maintaince effort of your code.  This</div><div class="line"><a name="l00263"></a><span class="lineno">  263</span>&#160;is more robust when anticipating possible changes of the schema(s) and/or the</div><div class="line"><a name="l00264"></a><span class="lineno">  264</span>&#160;binding URI(s) and/or the tooling algorithms.</div><div class="line"><a name="l00265"></a><span class="lineno">  265</span>&#160;</div><div class="line"><a name="l00266"></a><span class="lineno">  266</span>&#160;The first and foremost important thing to do is to define prefix-URI bindings</div><div class="line"><a name="l00267"></a><span class="lineno">  267</span>&#160;for our C/C++ code by adding the following line(s) to our &lt;i&gt;`typemap.dat`&lt;/i&gt; or make</div><div class="line"><a name="l00268"></a><span class="lineno">  268</span>&#160;a copy of this file and add the line(s) that bind our choice of prefix name to</div><div class="line"><a name="l00269"></a><span class="lineno">  269</span>&#160;each URI:</div><div class="line"><a name="l00270"></a><span class="lineno">  270</span>&#160;</div><div class="line"><a name="l00271"></a><span class="lineno">  271</span>&#160;    prefix = &quot;URI&quot;</div><div class="line"><a name="l00272"></a><span class="lineno">  272</span>&#160;</div><div class="line"><a name="l00273"></a><span class="lineno">  273</span>&#160;For example, to use `g` as a prefix for the &quot;urn:graph&quot; XML namespace:</div><div class="line"><a name="l00274"></a><span class="lineno">  274</span>&#160;</div><div class="line"><a name="l00275"></a><span class="lineno">  275</span>&#160;    g = &quot;urn:graph&quot;</div><div class="line"><a name="l00276"></a><span class="lineno">  276</span>&#160;</div><div class="line"><a name="l00277"></a><span class="lineno">  277</span>&#160;This produces `g__name` C/C++ type names that are bound to the &quot;urn:graph&quot;</div><div class="line"><a name="l00278"></a><span class="lineno">  278</span>&#160;schema by association of `g` to the generated C/C++ types.</div><div class="line"><a name="l00279"></a><span class="lineno">  279</span>&#160;</div><div class="line"><a name="l00280"></a><span class="lineno">  280</span>&#160;This means that &lt;i&gt;`&lt;g:name xmlns:g=&quot;urn:graph&quot;&gt;`&lt;/i&gt; is parsed as an instance of a</div><div class="line"><a name="l00281"></a><span class="lineno">  281</span>&#160;`g__name` C/C++ type.  Also &lt;i&gt;`&lt;x:name xmlns:x=&quot;urn:graph&quot;&gt;`&lt;/i&gt; parses as an</div><div class="line"><a name="l00282"></a><span class="lineno">  282</span>&#160;instance of `g__name`, because the prefix &lt;i&gt;`x`&lt;/i&gt; has the same URI value</div><div class="line"><a name="l00283"></a><span class="lineno">  283</span>&#160;&lt;i&gt;`urn:graph`&lt;/i&gt;.  Prefixes in XML have local scopes (like variables in a block).</div><div class="line"><a name="l00284"></a><span class="lineno">  284</span>&#160;</div><div class="line"><a name="l00285"></a><span class="lineno">  285</span>&#160;The first run of wsdl2h will reveal the XML namespace URIs, so you do not need</div><div class="line"><a name="l00286"></a><span class="lineno">  286</span>&#160;to search WSDLs and XSD files for all of the target namespaces.  Just copy them</div><div class="line"><a name="l00287"></a><span class="lineno">  287</span>&#160;from the generated header file after the first run into &lt;i&gt;`typemap.dat`&lt;/i&gt; for</div><div class="line"><a name="l00288"></a><span class="lineno">  288</span>&#160;editing.</div><div class="line"><a name="l00289"></a><span class="lineno">  289</span>&#160;</div><div class="line"><a name="l00290"></a><span class="lineno">  290</span>&#160;@note Only define a namespace prefix once in &lt;i&gt;`typemap.dat`&lt;/i&gt;.  That is, do not</div><div class="line"><a name="l00291"></a><span class="lineno">  291</span>&#160;use the same prefix for multiple XML namespace URIs.  This is to avoid</div><div class="line"><a name="l00292"></a><span class="lineno">  292</span>&#160;namespace conflicts that may cause failed builds and failures in XML parsing</div><div class="line"><a name="l00293"></a><span class="lineno">  293</span>&#160;and XML schema validation.</div><div class="line"><a name="l00294"></a><span class="lineno">  294</span>&#160;</div><div class="line"><a name="l00295"></a><span class="lineno">  295</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00296"></a><span class="lineno">  296</span>&#160;</div><div class="line"><a name="l00297"></a><span class="lineno">  297</span>&#160;XSD type bindings                                                    {#typemap2}</div><div class="line"><a name="l00298"></a><span class="lineno">  298</span>&#160;-----------------</div><div class="line"><a name="l00299"></a><span class="lineno">  299</span>&#160;</div><div class="line"><a name="l00300"></a><span class="lineno">  300</span>&#160;Custom C/C++ type bindings can be declared in &lt;i&gt;`typemap.dat`&lt;/i&gt; to associate C/C++</div><div class="line"><a name="l00301"></a><span class="lineno">  301</span>&#160;types with specific schema types.  These type bindings have four parts:</div><div class="line"><a name="l00302"></a><span class="lineno">  302</span>&#160;</div><div class="line"><a name="l00303"></a><span class="lineno">  303</span>&#160;    prefix__type = declaration | use | ptr-use</div><div class="line"><a name="l00304"></a><span class="lineno">  304</span>&#160;</div><div class="line"><a name="l00305"></a><span class="lineno">  305</span>&#160;where</div><div class="line"><a name="l00306"></a><span class="lineno">  306</span>&#160;</div><div class="line"><a name="l00307"></a><span class="lineno">  307</span>&#160;- &lt;b&gt;`prefix__type`&lt;/b&gt; is the schema type to be customized (the &lt;b&gt;`prefix__type`&lt;/b&gt; name</div><div class="line"><a name="l00308"></a><span class="lineno">  308</span>&#160;  uses the common double underscore naming convention);</div><div class="line"><a name="l00309"></a><span class="lineno">  309</span>&#160;</div><div class="line"><a name="l00310"></a><span class="lineno">  310</span>&#160;- &lt;b&gt;`declaration`&lt;/b&gt; declares the C/C++ type in the wsdl2h-generated header file.</div><div class="line"><a name="l00311"></a><span class="lineno">  311</span>&#160;  This part can be empty if no explicit declaration is needed;</div><div class="line"><a name="l00312"></a><span class="lineno">  312</span>&#160;</div><div class="line"><a name="l00313"></a><span class="lineno">  313</span>&#160;- &lt;b&gt;`use`&lt;/b&gt; is an optional part that specifies how the C/C++ type is used in the</div><div class="line"><a name="l00314"></a><span class="lineno">  314</span>&#160;  code.  When omitted, it is the same as &lt;b&gt;`prefix__type`&lt;/b&gt;;</div><div class="line"><a name="l00315"></a><span class="lineno">  315</span>&#160;</div><div class="line"><a name="l00316"></a><span class="lineno">  316</span>&#160;- &lt;b&gt;`ptr-use`&lt;/b&gt; is an optional part that specifies how the type is used as a pointer</div><div class="line"><a name="l00317"></a><span class="lineno">  317</span>&#160;  type.  By default it is the &lt;b&gt;`use`&lt;/b&gt; type name with a &lt;b&gt;`*`&lt;/b&gt; or C++11</div><div class="line"><a name="l00318"></a><span class="lineno">  318</span>&#160;  &lt;b&gt;`std::shared_ptr&lt;type&gt;`&lt;/b&gt; when enabled (see further below).  If &lt;b&gt;`use`&lt;/b&gt; is already a</div><div class="line"><a name="l00319"></a><span class="lineno">  319</span>&#160;  pointer type by the presence of a &lt;b&gt;`*`&lt;/b&gt; in the &lt;b&gt;`use`&lt;/b&gt; part, then the default</div><div class="line"><a name="l00320"></a><span class="lineno">  320</span>&#160;  &lt;b&gt;`ptr-use`&lt;/b&gt; type is the same as the &lt;b&gt;`use`&lt;/b&gt; type (that is, no double</div><div class="line"><a name="l00321"></a><span class="lineno">  321</span>&#160;  pointers &lt;b&gt;`**`&lt;/b&gt; will be created in this case).</div><div class="line"><a name="l00322"></a><span class="lineno">  322</span>&#160;</div><div class="line"><a name="l00323"></a><span class="lineno">  323</span>&#160;For example, to map &lt;i&gt;`xsd:duration`&lt;/i&gt; to a `long long` (`LONG64`) type that holds</div><div class="line"><a name="l00324"></a><span class="lineno">  324</span>&#160;millisecond duration values, we can use the custom serializer declared in</div><div class="line"><a name="l00325"></a><span class="lineno">  325</span>&#160;&lt;i&gt;`gsoap/custom/duration.h`&lt;/i&gt; by adding the following line to &lt;i&gt;`typemap.dat`&lt;/i&gt;:</div><div class="line"><a name="l00326"></a><span class="lineno">  326</span>&#160;</div><div class="line"><a name="l00327"></a><span class="lineno">  327</span>&#160;    xsd__duration = #import &quot;custom/duration.h&quot;</div><div class="line"><a name="l00328"></a><span class="lineno">  328</span>&#160;</div><div class="line"><a name="l00329"></a><span class="lineno">  329</span>&#160;Here, we omitted the second and third parts, because `xsd__duration` is the</div><div class="line"><a name="l00330"></a><span class="lineno">  330</span>&#160;name that wsdl2h uses for this type in our generated code so we should leave</div><div class="line"><a name="l00331"></a><span class="lineno">  331</span>&#160;the &lt;b&gt;`use`&lt;/b&gt; part unspecified.  The third part is omitted to let wsdl2h use</div><div class="line"><a name="l00332"></a><span class="lineno">  332</span>&#160;`xsd__duration *` for pointers or `std::shared_ptr&lt;xsd__duration&gt;` if smart</div><div class="line"><a name="l00333"></a><span class="lineno">  333</span>&#160;pointers are enabled.</div><div class="line"><a name="l00334"></a><span class="lineno">  334</span>&#160;</div><div class="line"><a name="l00335"></a><span class="lineno">  335</span>&#160;To map &lt;i&gt;`xsd:string`&lt;/i&gt; to `wchar_t*` wide strings for C source code output:</div><div class="line"><a name="l00336"></a><span class="lineno">  336</span>&#160;</div><div class="line"><a name="l00337"></a><span class="lineno">  337</span>&#160;    xsd__string = | wchar_t* | wchar_t*</div><div class="line"><a name="l00338"></a><span class="lineno">  338</span>&#160;</div><div class="line"><a name="l00339"></a><span class="lineno">  339</span>&#160;For C++ we can use the `std::wstring` wide string:</div><div class="line"><a name="l00340"></a><span class="lineno">  340</span>&#160;</div><div class="line"><a name="l00341"></a><span class="lineno">  341</span>&#160;    xsd__string = | std::wstring</div><div class="line"><a name="l00342"></a><span class="lineno">  342</span>&#160;</div><div class="line"><a name="l00343"></a><span class="lineno">  343</span>&#160;Note that the first part is empty, because these types do not require a</div><div class="line"><a name="l00344"></a><span class="lineno">  344</span>&#160;declaration.  A &lt;b&gt;`ptr-use`&lt;/b&gt; part is also defined for `wchar_t*`, but this</div><div class="line"><a name="l00345"></a><span class="lineno">  345</span>&#160;is actually needed because the wsdl2h tool recognizes that the &lt;b&gt;`use`&lt;/b&gt;</div><div class="line"><a name="l00346"></a><span class="lineno">  346</span>&#160;part `wchar_t*` is already a pointer.  By contrast, when using 8-bit strings,</div><div class="line"><a name="l00347"></a><span class="lineno">  347</span>&#160;it is recommended to use the `SOAP_C_UTFSTRING` flag to enable UTF-8 formatted</div><div class="line"><a name="l00348"></a><span class="lineno">  348</span>&#160;strings.</div><div class="line"><a name="l00349"></a><span class="lineno">  349</span>&#160;</div><div class="line"><a name="l00350"></a><span class="lineno">  350</span>&#160;When the &lt;b&gt;`ptr-use`&lt;/b&gt; part is not specified, it will be auto-generated</div><div class="line"><a name="l00351"></a><span class="lineno">  351</span>&#160;as pointer `T*` for &lt;b&gt;`use`&lt;/b&gt; type `T` or `std::shared_ptr&lt;T&gt;` when</div><div class="line"><a name="l00352"></a><span class="lineno">  352</span>&#160;the variable `$POINTER = std::shared`, see</div><div class="line"><a name="l00353"></a><span class="lineno">  353</span>&#160;[the special variables $CONTAINER, $POINTER, $SIZE and $OPTIONAL](#typemap5).</div><div class="line"><a name="l00354"></a><span class="lineno">  354</span>&#160;</div><div class="line"><a name="l00355"></a><span class="lineno">  355</span>&#160;The &lt;b&gt;`declaration`&lt;/b&gt; part need not be empty, for example if a type must be</div><div class="line"><a name="l00356"></a><span class="lineno">  356</span>&#160;declared.  For example:</div><div class="line"><a name="l00357"></a><span class="lineno">  357</span>&#160;</div><div class="line"><a name="l00358"></a><span class="lineno">  358</span>&#160;    xsd__string = typedef std::string mystring; | mystring | std::optional&lt;mystring&gt;</div><div class="line"><a name="l00359"></a><span class="lineno">  359</span>&#160;</div><div class="line"><a name="l00360"></a><span class="lineno">  360</span>&#160;When a auto-generated &lt;b&gt;`declaration`&lt;/b&gt; should be preserved but the</div><div class="line"><a name="l00361"></a><span class="lineno">  361</span>&#160;&lt;b&gt;`use`&lt;/b&gt; or &lt;b&gt;`ptr-use`&lt;/b&gt; parts must be redefined, then we use an</div><div class="line"><a name="l00362"></a><span class="lineno">  362</span>&#160;ellipsis for the &lt;b&gt;`declaration`&lt;/b&gt; part:</div><div class="line"><a name="l00363"></a><span class="lineno">  363</span>&#160;</div><div class="line"><a name="l00364"></a><span class="lineno">  364</span>&#160;    prefix__type = ... | use | ptr-use</div><div class="line"><a name="l00365"></a><span class="lineno">  365</span>&#160;</div><div class="line"><a name="l00366"></a><span class="lineno">  366</span>&#160;The &lt;b&gt;`ptr-use`&lt;/b&gt; part is also useful to map schema polymorphic types to C</div><div class="line"><a name="l00367"></a><span class="lineno">  367</span>&#160;types for example, where we need to be able to both handle a base type and its</div><div class="line"><a name="l00368"></a><span class="lineno">  368</span>&#160;extensions as per schema extensibility.  Say we have a base type called</div><div class="line"><a name="l00369"></a><span class="lineno">  369</span>&#160;&lt;i&gt;`ns:base`&lt;/i&gt; that is extended, then we can remap this to a C type that</div><div class="line"><a name="l00370"></a><span class="lineno">  370</span>&#160;permits referening the extended types via a `void*` as follows:</div><div class="line"><a name="l00371"></a><span class="lineno">  371</span>&#160;</div><div class="line"><a name="l00372"></a><span class="lineno">  372</span>&#160;    ns__base = ... | int __type_base; void*</div><div class="line"><a name="l00373"></a><span class="lineno">  373</span>&#160;</div><div class="line"><a name="l00374"></a><span class="lineno">  374</span>&#160;such that `__type_base` and `void*` will be used to (de)serialize any data</div><div class="line"><a name="l00375"></a><span class="lineno">  375</span>&#160;type, including base and its derived types.  The `__type_base` integer is set</div><div class="line"><a name="l00376"></a><span class="lineno">  376</span>&#160;to a `SOAP_TYPE_T` value to indicate what type of data the `void*` pointer</div><div class="line"><a name="l00377"></a><span class="lineno">  377</span>&#160;points to.</div><div class="line"><a name="l00378"></a><span class="lineno">  378</span>&#160;</div><div class="line"><a name="l00379"></a><span class="lineno">  379</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00380"></a><span class="lineno">  380</span>&#160;</div><div class="line"><a name="l00381"></a><span class="lineno">  381</span>&#160;Custom serializers for XSD types                                       {#custom}</div><div class="line"><a name="l00382"></a><span class="lineno">  382</span>&#160;--------------------------------</div><div class="line"><a name="l00383"></a><span class="lineno">  383</span>&#160;</div><div class="line"><a name="l00384"></a><span class="lineno">  384</span>&#160;In the previous part we saw how a custom serializer is used to bind</div><div class="line"><a name="l00385"></a><span class="lineno">  385</span>&#160;&lt;i&gt;`xsd:duration`&lt;/i&gt; to a `long long` (`LONG64` or `int64_t`) type to store millisecond</div><div class="line"><a name="l00386"></a><span class="lineno">  386</span>&#160;duration values:</div><div class="line"><a name="l00387"></a><span class="lineno">  387</span>&#160;</div><div class="line"><a name="l00388"></a><span class="lineno">  388</span>&#160;    xsd__duration = #import &quot;custom/duration.h&quot;</div><div class="line"><a name="l00389"></a><span class="lineno">  389</span>&#160;</div><div class="line"><a name="l00390"></a><span class="lineno">  390</span>&#160;The `xsd__duration` type is an alias of `long long` (`LONG64` or `int64_t`).</div><div class="line"><a name="l00391"></a><span class="lineno">  391</span>&#160;</div><div class="line"><a name="l00392"></a><span class="lineno">  392</span>&#160;While wsdl2h will use this binding declared in &lt;i&gt;`typemap.dat`&lt;/i&gt;</div><div class="line"><a name="l00393"></a><span class="lineno">  393</span>&#160;automatically, you will also need to compile &lt;i&gt;`gsoap/custom/duration.c`&lt;/i&gt;.</div><div class="line"><a name="l00394"></a><span class="lineno">  394</span>&#160;Each custom serializer has an interface header file to be imported into another</div><div class="line"><a name="l00395"></a><span class="lineno">  395</span>&#160;interface header file that declares the custom type for soapcpp2 and a</div><div class="line"><a name="l00396"></a><span class="lineno">  396</span>&#160;serializer implementation file written in C, which should be compiled with the</div><div class="line"><a name="l00397"></a><span class="lineno">  397</span>&#160;application.  You can compile these in C++ (rename files to &lt;i&gt;`.cpp`&lt;/i&gt; if</div><div class="line"><a name="l00398"></a><span class="lineno">  398</span>&#160;needed).</div><div class="line"><a name="l00399"></a><span class="lineno">  399</span>&#160;</div><div class="line"><a name="l00400"></a><span class="lineno">  400</span>&#160;A custom serializer is declared in an interface header file for soapcpp2 using</div><div class="line"><a name="l00401"></a><span class="lineno">  401</span>&#160;`extern typedef`.  The typedef name declared is serializable, whereas the</div><div class="line"><a name="l00402"></a><span class="lineno">  402</span>&#160;type on which it is based is not serializable.  This declaration can be</div><div class="line"><a name="l00403"></a><span class="lineno">  403</span>&#160;combined with `volatile` when the type should not be redeclared, see</div><div class="line"><a name="l00404"></a><span class="lineno">  404</span>&#160;[volatile classes and structs](#toxsd9-2).  For example, the custom serializer</div><div class="line"><a name="l00405"></a><span class="lineno">  405</span>&#160;for `struct tm` is the type `xsd__datetime` declared as follows in</div><div class="line"><a name="l00406"></a><span class="lineno">  406</span>&#160;`gsoap/custom/struct_tm.h`:</div><div class="line"><a name="l00407"></a><span class="lineno">  407</span>&#160;</div><div class="line"><a name="l00408"></a><span class="lineno">  408</span>&#160;~~~{.cpp}</div><div class="line"><a name="l00409"></a><span class="lineno">  409</span>&#160;    extern typedef volatile struct tm</div><div class="line"><a name="l00410"></a><span class="lineno">  410</span>&#160;    {</div><div class="line"><a name="l00411"></a><span class="lineno">  411</span>&#160;        int   tm_sec;   ///&lt; seconds (0 - 60)</div><div class="line"><a name="l00412"></a><span class="lineno">  412</span>&#160;        int   tm_min;   ///&lt; minutes (0 - 59)</div><div class="line"><a name="l00413"></a><span class="lineno">  413</span>&#160;        int   tm_hour;  ///&lt; hours (0 - 23)</div><div class="line"><a name="l00414"></a><span class="lineno">  414</span>&#160;        int   tm_mday;  ///&lt; day of month (1 - 31)</div><div class="line"><a name="l00415"></a><span class="lineno">  415</span>&#160;        int   tm_mon;   ///&lt; month of year (0 - 11)</div><div class="line"><a name="l00416"></a><span class="lineno">  416</span>&#160;        int   tm_year;  ///&lt; year - 1900</div><div class="line"><a name="l00417"></a><span class="lineno">  417</span>&#160;        int   tm_wday;  ///&lt; day of week (Sunday = 0) (NOT USED)</div><div class="line"><a name="l00418"></a><span class="lineno">  418</span>&#160;        int   tm_yday;  ///&lt; day of year (0 - 365) (NOT USED)</div><div class="line"><a name="l00419"></a><span class="lineno">  419</span>&#160;        int   tm_isdst; ///&lt; is summer time in effect?</div><div class="line"><a name="l00420"></a><span class="lineno">  420</span>&#160;        char* tm_zone;  ///&lt; abbreviation of timezone (NOT USED)</div><div class="line"><a name="l00421"></a><span class="lineno">  421</span>&#160;    } xsd__dateTime;</div><div class="line"><a name="l00422"></a><span class="lineno">  422</span>&#160;~~~</div><div class="line"><a name="l00423"></a><span class="lineno">  423</span>&#160;</div><div class="line"><a name="l00424"></a><span class="lineno">  424</span>&#160;Another example is `xsd__duration` as a custom serializer for the C++11 type</div><div class="line"><a name="l00425"></a><span class="lineno">  425</span>&#160;`std::chrono::nanoseconds`:</div><div class="line"><a name="l00426"></a><span class="lineno">  426</span>&#160;</div><div class="line"><a name="l00427"></a><span class="lineno">  427</span>&#160;~~~{.cpp}</div><div class="line"><a name="l00428"></a><span class="lineno">  428</span>&#160;    extern typedef class std::chrono::nanoseconds xsd__duration;</div><div class="line"><a name="l00429"></a><span class="lineno">  429</span>&#160;~~~</div><div class="line"><a name="l00430"></a><span class="lineno">  430</span>&#160;</div><div class="line"><a name="l00431"></a><span class="lineno">  431</span>&#160;Next, we present all pre-defined custom serializers that are available to you.</div><div class="line"><a name="l00432"></a><span class="lineno">  432</span>&#160;</div><div class="line"><a name="l00433"></a><span class="lineno">  433</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00434"></a><span class="lineno">  434</span>&#160;</div><div class="line"><a name="l00435"></a><span class="lineno">  435</span>&#160;### xsd:integer                                                      {#custom-1}</div><div class="line"><a name="l00436"></a><span class="lineno">  436</span>&#160;</div><div class="line"><a name="l00437"></a><span class="lineno">  437</span>&#160;The wsdl2h tool maps &lt;i&gt;`xsd:integer`&lt;/i&gt; to a string by default.  To map &lt;i&gt;`xsd:integer`&lt;/i&gt; to</div><div class="line"><a name="l00438"></a><span class="lineno">  438</span>&#160;the 128 bit big int type `__int128_t`:</div><div class="line"><a name="l00439"></a><span class="lineno">  439</span>&#160;</div><div class="line"><a name="l00440"></a><span class="lineno">  440</span>&#160;    xsd__integer = #import &quot;custom/int128.h&quot;</div><div class="line"><a name="l00441"></a><span class="lineno">  441</span>&#160;</div><div class="line"><a name="l00442"></a><span class="lineno">  442</span>&#160;The `xsd__integer` type is an alias of `__int128_t`.</div><div class="line"><a name="l00443"></a><span class="lineno">  443</span>&#160;</div><div class="line"><a name="l00444"></a><span class="lineno">  444</span>&#160;@warning Beware that the &lt;i&gt;`xsd:integer`&lt;/i&gt; value space of integers is in principle</div><div class="line"><a name="l00445"></a><span class="lineno">  445</span>&#160;unbounded and values can be of arbitrary length.  A value range fault</div><div class="line"><a name="l00446"></a><span class="lineno">  446</span>&#160;`SOAP_TYPE` (value exceeds native representation) or `SOAP_LENGTH` (value</div><div class="line"><a name="l00447"></a><span class="lineno">  447</span>&#160;exceeds range bounds) will be thrown by the deserializer if the value is out of</div><div class="line"><a name="l00448"></a><span class="lineno">  448</span>&#160;range.</div><div class="line"><a name="l00449"></a><span class="lineno">  449</span>&#160;</div><div class="line"><a name="l00450"></a><span class="lineno">  450</span>&#160;Other XSD integer types that are restrictions of &lt;i&gt;`xsd:integer`&lt;/i&gt;, are</div><div class="line"><a name="l00451"></a><span class="lineno">  451</span>&#160;&lt;i&gt;`xsd:nonNegativeInteger`&lt;/i&gt; and &lt;i&gt;`xsd:nonPositiveInteger`&lt;/i&gt;, which are further restricted</div><div class="line"><a name="l00452"></a><span class="lineno">  452</span>&#160;by &lt;i&gt;`xsd:positiveInteger`&lt;/i&gt; and &lt;i&gt;`xsd:negativeInteger`&lt;/i&gt;.  To bind these types to</div><div class="line"><a name="l00453"></a><span class="lineno">  453</span>&#160;`__int128_t` add the following definitions to &lt;i&gt;`typemap.dat`&lt;/i&gt;:</div><div class="line"><a name="l00454"></a><span class="lineno">  454</span>&#160;</div><div class="line"><a name="l00455"></a><span class="lineno">  455</span>&#160;    xsd__nonNegativeInteger = typedef xsd__integer xsd__nonNegativeInteger 0 :    ;</div><div class="line"><a name="l00456"></a><span class="lineno">  456</span>&#160;    xsd__nonPositiveInteger = typedef xsd__integer xsd__nonPositiveInteger   : 0  ;</div><div class="line"><a name="l00457"></a><span class="lineno">  457</span>&#160;    xsd__positiveInteger    = typedef xsd__integer xsd__positiveInteger    1 :    ;</div><div class="line"><a name="l00458"></a><span class="lineno">  458</span>&#160;    xsd__negativeInteger    = typedef xsd__integer xsd__negativeInteger      : -1 ;</div><div class="line"><a name="l00459"></a><span class="lineno">  459</span>&#160;</div><div class="line"><a name="l00460"></a><span class="lineno">  460</span>&#160;Or simply uncomment these definitions in &lt;i&gt;`typemap.dat`&lt;/i&gt; when you are using the</div><div class="line"><a name="l00461"></a><span class="lineno">  461</span>&#160;latest gSOAP releases.</div><div class="line"><a name="l00462"></a><span class="lineno">  462</span>&#160;</div><div class="line"><a name="l00463"></a><span class="lineno">  463</span>&#160;@note If `__int128_t` 128 bit integers are not supported on your platform and if it</div><div class="line"><a name="l00464"></a><span class="lineno">  464</span>&#160;is certain that &lt;i&gt;`xsd:integer`&lt;/i&gt; values are within 64 bit value bounds for your</div><div class="line"><a name="l00465"></a><span class="lineno">  465</span>&#160;application&#39;s use, then you can map this type to `LONG64`:</div><div class="line"><a name="l00466"></a><span class="lineno">  466</span>&#160;</div><div class="line"><a name="l00467"></a><span class="lineno">  467</span>&#160;    xsd__integer = typedef LONG64 xsd__integer;</div><div class="line"><a name="l00468"></a><span class="lineno">  468</span>&#160;</div><div class="line"><a name="l00469"></a><span class="lineno">  469</span>&#160;@note Again, a value range fault `SOAP_TYPE` or `SOAP_LENGTH` will be thrown by</div><div class="line"><a name="l00470"></a><span class="lineno">  470</span>&#160;the deserializer if the value is out of range.</div><div class="line"><a name="l00471"></a><span class="lineno">  471</span>&#160;</div><div class="line"><a name="l00472"></a><span class="lineno">  472</span>&#160;After running wsdl2h and soapcpp2, compile &lt;i&gt;`gsoap/custom/int128.c`&lt;/i&gt; with your project.</div><div class="line"><a name="l00473"></a><span class="lineno">  473</span>&#160;</div><div class="line"><a name="l00474"></a><span class="lineno">  474</span>&#160;@see Section [numerical types](#toxsd5).</div><div class="line"><a name="l00475"></a><span class="lineno">  475</span>&#160;</div><div class="line"><a name="l00476"></a><span class="lineno">  476</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00477"></a><span class="lineno">  477</span>&#160;</div><div class="line"><a name="l00478"></a><span class="lineno">  478</span>&#160;### xsd:decimal                                                      {#custom-2}</div><div class="line"><a name="l00479"></a><span class="lineno">  479</span>&#160;</div><div class="line"><a name="l00480"></a><span class="lineno">  480</span>&#160;The wsdl2h tool maps &lt;i&gt;`xsd:decimal`&lt;/i&gt; to a string by default.  To map &lt;i&gt;`xsd:decimal`&lt;/i&gt; to</div><div class="line"><a name="l00481"></a><span class="lineno">  481</span>&#160;extended precision floating point:</div><div class="line"><a name="l00482"></a><span class="lineno">  482</span>&#160;</div><div class="line"><a name="l00483"></a><span class="lineno">  483</span>&#160;    xsd__decimal = #import &quot;custom/long_double.h&quot; | long double</div><div class="line"><a name="l00484"></a><span class="lineno">  484</span>&#160;</div><div class="line"><a name="l00485"></a><span class="lineno">  485</span>&#160;By contrast to all other custom serializers, this serializer enables `long</div><div class="line"><a name="l00486"></a><span class="lineno">  486</span>&#160;double` natively without requiring a new binding name (`xsd__decimal` is NOT</div><div class="line"><a name="l00487"></a><span class="lineno">  487</span>&#160;defined).</div><div class="line"><a name="l00488"></a><span class="lineno">  488</span>&#160;</div><div class="line"><a name="l00489"></a><span class="lineno">  489</span>&#160;If your system supports &lt;i&gt;`quadmath.h`&lt;/i&gt; quadruple precision floating point</div><div class="line"><a name="l00490"></a><span class="lineno">  490</span>&#160;`__float128`, you can map &lt;i&gt;`xsd:decimal`&lt;/i&gt; to `xsd__decimal` that is an alias of</div><div class="line"><a name="l00491"></a><span class="lineno">  491</span>&#160;`__float128`:</div><div class="line"><a name="l00492"></a><span class="lineno">  492</span>&#160;</div><div class="line"><a name="l00493"></a><span class="lineno">  493</span>&#160;    xsd__decimal = #import &quot;custom/float128.h&quot;</div><div class="line"><a name="l00494"></a><span class="lineno">  494</span>&#160;</div><div class="line"><a name="l00495"></a><span class="lineno">  495</span>&#160;@warning Beware that &lt;i&gt;`xsd:decimal`&lt;/i&gt; is in principle a decimal value with arbitraty</div><div class="line"><a name="l00496"></a><span class="lineno">  496</span>&#160;lengths.  A value range fault `SOAP_TYPE` will be thrown by the deserializer if</div><div class="line"><a name="l00497"></a><span class="lineno">  497</span>&#160;the value is out of range.</div><div class="line"><a name="l00498"></a><span class="lineno">  498</span>&#160;</div><div class="line"><a name="l00499"></a><span class="lineno">  499</span>&#160;In the XML payload the special values &lt;i&gt;`INF`&lt;/i&gt;, &lt;i&gt;`-INF`&lt;/i&gt;, &lt;i&gt;`NaN`&lt;/i&gt;</div><div class="line"><a name="l00500"></a><span class="lineno">  500</span>&#160;represent plus or minus infinity and not-a-number, respectively.</div><div class="line"><a name="l00501"></a><span class="lineno">  501</span>&#160;</div><div class="line"><a name="l00502"></a><span class="lineno">  502</span>&#160;After running wsdl2h and soapcpp2, compile &lt;i&gt;`gsoap/custom/long_double.c`&lt;/i&gt; with your</div><div class="line"><a name="l00503"></a><span class="lineno">  503</span>&#160;project.</div><div class="line"><a name="l00504"></a><span class="lineno">  504</span>&#160;</div><div class="line"><a name="l00505"></a><span class="lineno">  505</span>&#160;@see Section [numerical types](#toxsd5).</div><div class="line"><a name="l00506"></a><span class="lineno">  506</span>&#160;</div><div class="line"><a name="l00507"></a><span class="lineno">  507</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00508"></a><span class="lineno">  508</span>&#160;</div><div class="line"><a name="l00509"></a><span class="lineno">  509</span>&#160;### xsd:dateTime                                                     {#custom-3}</div><div class="line"><a name="l00510"></a><span class="lineno">  510</span>&#160;</div><div class="line"><a name="l00511"></a><span class="lineno">  511</span>&#160;The wsdl2h tool maps &lt;i&gt;`xsd:dateTime`&lt;/i&gt; to `time_t` by default.</div><div class="line"><a name="l00512"></a><span class="lineno">  512</span>&#160;</div><div class="line"><a name="l00513"></a><span class="lineno">  513</span>&#160;The trouble with `time_t` when represented as 32 bit `long` integers is that it</div><div class="line"><a name="l00514"></a><span class="lineno">  514</span>&#160;is limited to dates between 1970 and 2038.  A 64 bit `time_t` is safe to use if</div><div class="line"><a name="l00515"></a><span class="lineno">  515</span>&#160;the target platform supports it, but lack of 64 bit `time_t` portability may</div><div class="line"><a name="l00516"></a><span class="lineno">  516</span>&#160;still cause date range issues.</div><div class="line"><a name="l00517"></a><span class="lineno">  517</span>&#160;</div><div class="line"><a name="l00518"></a><span class="lineno">  518</span>&#160;For this reason `struct tm` should be used to represent wider date ranges.  This</div><div class="line"><a name="l00519"></a><span class="lineno">  519</span>&#160;custom serializer avoids using date and time information in `time_t`.  You get</div><div class="line"><a name="l00520"></a><span class="lineno">  520</span>&#160;the raw date and time information.  You only lose the day of the week</div><div class="line"><a name="l00521"></a><span class="lineno">  521</span>&#160;information.  It is always Sunday (`tm_wday=0`).</div><div class="line"><a name="l00522"></a><span class="lineno">  522</span>&#160;</div><div class="line"><a name="l00523"></a><span class="lineno">  523</span>&#160;To map &lt;i&gt;`xsd:dateTime`&lt;/i&gt; to `xsd__dateTime` which is an alias of `struct tm`:</div><div class="line"><a name="l00524"></a><span class="lineno">  524</span>&#160;</div><div class="line"><a name="l00525"></a><span class="lineno">  525</span>&#160;    xsd__dateTime = #import &quot;custom/struct_tm.h&quot;</div><div class="line"><a name="l00526"></a><span class="lineno">  526</span>&#160;</div><div class="line"><a name="l00527"></a><span class="lineno">  527</span>&#160;If the limited date range of `time_t` is not a problem but you want to increase</div><div class="line"><a name="l00528"></a><span class="lineno">  528</span>&#160;the time precision with fractional seconds, then we suggest to map &lt;i&gt;`xsd:dateTime`&lt;/i&gt;</div><div class="line"><a name="l00529"></a><span class="lineno">  529</span>&#160;to `struct timeval`:</div><div class="line"><a name="l00530"></a><span class="lineno">  530</span>&#160;</div><div class="line"><a name="l00531"></a><span class="lineno">  531</span>&#160;    xsd__dateTime = #import &quot;custom/struct_timeval.h&quot;</div><div class="line"><a name="l00532"></a><span class="lineno">  532</span>&#160;</div><div class="line"><a name="l00533"></a><span class="lineno">  533</span>&#160;If the limited date range of `time_t` is not a problem but you want to use the</div><div class="line"><a name="l00534"></a><span class="lineno">  534</span>&#160;C++11 time point type `std::chrono::system_clock::time_point` (which internally</div><div class="line"><a name="l00535"></a><span class="lineno">  535</span>&#160;uses `time_t`):</div><div class="line"><a name="l00536"></a><span class="lineno">  536</span>&#160;</div><div class="line"><a name="l00537"></a><span class="lineno">  537</span>&#160;    xsd__dateTime = #import &quot;custom/chrono_time_point.h&quot;</div><div class="line"><a name="l00538"></a><span class="lineno">  538</span>&#160;</div><div class="line"><a name="l00539"></a><span class="lineno">  539</span>&#160;Again, we should make sure that the dates will not exceed the date range when</div><div class="line"><a name="l00540"></a><span class="lineno">  540</span>&#160;using the default `time_t` binding for &lt;i&gt;`xsd:dateTime`&lt;/i&gt; or when binding</div><div class="line"><a name="l00541"></a><span class="lineno">  541</span>&#160;&lt;i&gt;`xsd:dateTime`&lt;/i&gt; to `struct timeval` or to `std::chrono::system_clock::time_point`.</div><div class="line"><a name="l00542"></a><span class="lineno">  542</span>&#160;These are safe to use in applications that use &lt;i&gt;`xsd:dateTime`&lt;/i&gt; to record date</div><div class="line"><a name="l00543"></a><span class="lineno">  543</span>&#160;stamps within a given window.  Otherwise, we recommend the `struct tm` custom</div><div class="line"><a name="l00544"></a><span class="lineno">  544</span>&#160;serializer.</div><div class="line"><a name="l00545"></a><span class="lineno">  545</span>&#160;</div><div class="line"><a name="l00546"></a><span class="lineno">  546</span>&#160;After running wsdl2h and soapcpp2, compile &lt;i&gt;`gsoap/custom/struct_tm.c`&lt;/i&gt; with your</div><div class="line"><a name="l00547"></a><span class="lineno">  547</span>&#160;project.</div><div class="line"><a name="l00548"></a><span class="lineno">  548</span>&#160;</div><div class="line"><a name="l00549"></a><span class="lineno">  549</span>&#160;You could even map &lt;i&gt;`xsd:dateTime`&lt;/i&gt; to a plain string (use `char*` with C and</div><div class="line"><a name="l00550"></a><span class="lineno">  550</span>&#160;`std::string` with C++).  For example:</div><div class="line"><a name="l00551"></a><span class="lineno">  551</span>&#160;</div><div class="line"><a name="l00552"></a><span class="lineno">  552</span>&#160;    xsd__dateTime = | char*</div><div class="line"><a name="l00553"></a><span class="lineno">  553</span>&#160;</div><div class="line"><a name="l00554"></a><span class="lineno">  554</span>&#160;@see Section [date and time types](#toxsd7).</div><div class="line"><a name="l00555"></a><span class="lineno">  555</span>&#160;</div><div class="line"><a name="l00556"></a><span class="lineno">  556</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00557"></a><span class="lineno">  557</span>&#160;</div><div class="line"><a name="l00558"></a><span class="lineno">  558</span>&#160;### xsd:date                                                         {#custom-4}</div><div class="line"><a name="l00559"></a><span class="lineno">  559</span>&#160;</div><div class="line"><a name="l00560"></a><span class="lineno">  560</span>&#160;The wsdl2h tool maps &lt;i&gt;`xsd:date`&lt;/i&gt; to a string by default.  We can map &lt;i&gt;`xsd:date`&lt;/i&gt; to</div><div class="line"><a name="l00561"></a><span class="lineno">  561</span>&#160;`struct tm`:</div><div class="line"><a name="l00562"></a><span class="lineno">  562</span>&#160;</div><div class="line"><a name="l00563"></a><span class="lineno">  563</span>&#160;    xsd__date = #import &quot;custom/struct_tm_date.h&quot;</div><div class="line"><a name="l00564"></a><span class="lineno">  564</span>&#160;</div><div class="line"><a name="l00565"></a><span class="lineno">  565</span>&#160;The `xsd__date` type is an alias of `struct tm`.  The serializer ignores the</div><div class="line"><a name="l00566"></a><span class="lineno">  566</span>&#160;time part and the deserializer only populates the date part of the struct,</div><div class="line"><a name="l00567"></a><span class="lineno">  567</span>&#160;setting the time to 00:00:00.  There is no unreasonable limit on the date range</div><div class="line"><a name="l00568"></a><span class="lineno">  568</span>&#160;because the year field is stored as an integer (`int`).</div><div class="line"><a name="l00569"></a><span class="lineno">  569</span>&#160;</div><div class="line"><a name="l00570"></a><span class="lineno">  570</span>&#160;After running wsdl2h and soapcpp2, compile &lt;i&gt;`gsoap/custom/struct_tm_date.c`&lt;/i&gt; with your</div><div class="line"><a name="l00571"></a><span class="lineno">  571</span>&#160;project.</div><div class="line"><a name="l00572"></a><span class="lineno">  572</span>&#160;</div><div class="line"><a name="l00573"></a><span class="lineno">  573</span>&#160;@see Section [date and time types](#toxsd7).</div><div class="line"><a name="l00574"></a><span class="lineno">  574</span>&#160;</div><div class="line"><a name="l00575"></a><span class="lineno">  575</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00576"></a><span class="lineno">  576</span>&#160;</div><div class="line"><a name="l00577"></a><span class="lineno">  577</span>&#160;### xsd:time                                                         {#custom-5}</div><div class="line"><a name="l00578"></a><span class="lineno">  578</span>&#160;</div><div class="line"><a name="l00579"></a><span class="lineno">  579</span>&#160;The wsdl2h tool maps &lt;i&gt;`xsd:time`&lt;/i&gt; to a string by default.  We can map &lt;i&gt;`xsd:time`&lt;/i&gt; to</div><div class="line"><a name="l00580"></a><span class="lineno">  580</span>&#160;an `unsigned long long` (`ULONG64` or `uint64_t`) integer with microsecond time</div><div class="line"><a name="l00581"></a><span class="lineno">  581</span>&#160;precision:</div><div class="line"><a name="l00582"></a><span class="lineno">  582</span>&#160;</div><div class="line"><a name="l00583"></a><span class="lineno">  583</span>&#160;    xsd__time = #import &quot;custom/long_time.h&quot;</div><div class="line"><a name="l00584"></a><span class="lineno">  584</span>&#160;</div><div class="line"><a name="l00585"></a><span class="lineno">  585</span>&#160;This type represents 00:00:00.000000 to 23:59:59.999999, from `0` to an upper</div><div class="line"><a name="l00586"></a><span class="lineno">  586</span>&#160;bound of `86399999999`.  A microsecond resolution means that a 1 second</div><div class="line"><a name="l00587"></a><span class="lineno">  587</span>&#160;increment requires an increment of 1000000 in the integer value.  The serializer</div><div class="line"><a name="l00588"></a><span class="lineno">  588</span>&#160;adds a UTC time zone.</div><div class="line"><a name="l00589"></a><span class="lineno">  589</span>&#160;</div><div class="line"><a name="l00590"></a><span class="lineno">  590</span>&#160;After running wsdl2h and soapcpp2, compile &lt;i&gt;`gsoap/custom/long_time.c`&lt;/i&gt; with your</div><div class="line"><a name="l00591"></a><span class="lineno">  591</span>&#160;project.</div><div class="line"><a name="l00592"></a><span class="lineno">  592</span>&#160;</div><div class="line"><a name="l00593"></a><span class="lineno">  593</span>&#160;@see Section [date and time types](#toxsd7).</div><div class="line"><a name="l00594"></a><span class="lineno">  594</span>&#160;</div><div class="line"><a name="l00595"></a><span class="lineno">  595</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00596"></a><span class="lineno">  596</span>&#160;</div><div class="line"><a name="l00597"></a><span class="lineno">  597</span>&#160;### xsd:duration                                                     {#custom-6}</div><div class="line"><a name="l00598"></a><span class="lineno">  598</span>&#160;</div><div class="line"><a name="l00599"></a><span class="lineno">  599</span>&#160;The wsdl2h tool maps &lt;i&gt;`xsd:duration`&lt;/i&gt; to a string by default, unless &lt;i&gt;`xsd:duration`&lt;/i&gt;</div><div class="line"><a name="l00600"></a><span class="lineno">  600</span>&#160;is mapped to a `long long` (`LONG64` or `int64_t`) type with with millisecond</div><div class="line"><a name="l00601"></a><span class="lineno">  601</span>&#160;(ms) time duration precision:</div><div class="line"><a name="l00602"></a><span class="lineno">  602</span>&#160;</div><div class="line"><a name="l00603"></a><span class="lineno">  603</span>&#160;    xsd__duration = #import &quot;custom/duration.h&quot;</div><div class="line"><a name="l00604"></a><span class="lineno">  604</span>&#160;</div><div class="line"><a name="l00605"></a><span class="lineno">  605</span>&#160;The `xsd__duration` type is a 64 bit signed integer that can represent</div><div class="line"><a name="l00606"></a><span class="lineno">  606</span>&#160;106,751,991,167 days forwards (positive) and backwards (negative) in time in</div><div class="line"><a name="l00607"></a><span class="lineno">  607</span>&#160;increments of 1 ms (1/1000 of a second).</div><div class="line"><a name="l00608"></a><span class="lineno">  608</span>&#160;</div><div class="line"><a name="l00609"></a><span class="lineno">  609</span>&#160;Rescaling of the duration value by may be needed when adding the duration value</div><div class="line"><a name="l00610"></a><span class="lineno">  610</span>&#160;to a `time_t` value, because `time_t` may or may not have a seconds resolution,</div><div class="line"><a name="l00611"></a><span class="lineno">  611</span>&#160;depending on the platform and possible changes to `time_t`.</div><div class="line"><a name="l00612"></a><span class="lineno">  612</span>&#160;</div><div class="line"><a name="l00613"></a><span class="lineno">  613</span>&#160;Rescaling is done automatically when you add a C++11 `std::chrono::nanoseconds`</div><div class="line"><a name="l00614"></a><span class="lineno">  614</span>&#160;value to a `std::chrono::system_clock::time_point` value.  To use</div><div class="line"><a name="l00615"></a><span class="lineno">  615</span>&#160;`std::chrono::nanoseconds` as &lt;i&gt;`xsd:duration`&lt;/i&gt;:</div><div class="line"><a name="l00616"></a><span class="lineno">  616</span>&#160;</div><div class="line"><a name="l00617"></a><span class="lineno">  617</span>&#160;    xsd__duration = #import &quot;custom/chrono_duration.h&quot;</div><div class="line"><a name="l00618"></a><span class="lineno">  618</span>&#160;</div><div class="line"><a name="l00619"></a><span class="lineno">  619</span>&#160;This type can represent 384,307,168 days (2^63 nanoseconds) forwards and</div><div class="line"><a name="l00620"></a><span class="lineno">  620</span>&#160;backwards in time in increments of 1 ns (1/1,000,000,000 of a second).</div><div class="line"><a name="l00621"></a><span class="lineno">  621</span>&#160;</div><div class="line"><a name="l00622"></a><span class="lineno">  622</span>&#160;Certain observations with respect to receiving durations in years and months</div><div class="line"><a name="l00623"></a><span class="lineno">  623</span>&#160;apply to both of these serializer decoders for &lt;i&gt;`xsd:duration`&lt;/i&gt;.</div><div class="line"><a name="l00624"></a><span class="lineno">  624</span>&#160;</div><div class="line"><a name="l00625"></a><span class="lineno">  625</span>&#160;After running wsdl2h and soapcpp2, compile &lt;i&gt;`gsoap/custom/duration.c`&lt;/i&gt; with your</div><div class="line"><a name="l00626"></a><span class="lineno">  626</span>&#160;project.</div><div class="line"><a name="l00627"></a><span class="lineno">  627</span>&#160;</div><div class="line"><a name="l00628"></a><span class="lineno">  628</span>&#160;@see Section [time duration types](#toxsd8).</div><div class="line"><a name="l00629"></a><span class="lineno">  629</span>&#160;</div><div class="line"><a name="l00630"></a><span class="lineno">  630</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00631"></a><span class="lineno">  631</span>&#160;</div><div class="line"><a name="l00632"></a><span class="lineno">  632</span>&#160;Custom Qt serializers for XSD types                                        {#qt}</div><div class="line"><a name="l00633"></a><span class="lineno">  633</span>&#160;-----------------------------------</div><div class="line"><a name="l00634"></a><span class="lineno">  634</span>&#160;</div><div class="line"><a name="l00635"></a><span class="lineno">  635</span>&#160;The gSOAP distribution includes several custom serializers for Qt types.  Also</div><div class="line"><a name="l00636"></a><span class="lineno">  636</span>&#160;Qt container classes are supported, see</div><div class="line"><a name="l00637"></a><span class="lineno">  637</span>&#160;[the special variables $CONTAINER, $POINTER, $SIZE and $OPTIONAL](#typemap5).</div><div class="line"><a name="l00638"></a><span class="lineno">  638</span>&#160;</div><div class="line"><a name="l00639"></a><span class="lineno">  639</span>&#160;This feature requires gSOAP 2.8.34 or higher and Qt 4.8 or higher.</div><div class="line"><a name="l00640"></a><span class="lineno">  640</span>&#160;</div><div class="line"><a name="l00641"></a><span class="lineno">  641</span>&#160;Each Qt custom serializer has an interface header file for soapcpp2 and a C++</div><div class="line"><a name="l00642"></a><span class="lineno">  642</span>&#160;implementation file to be compiled with your project.</div><div class="line"><a name="l00643"></a><span class="lineno">  643</span>&#160;</div><div class="line"><a name="l00644"></a><span class="lineno">  644</span>&#160;Other Qt primitive types that are Qt `typedef`s of C/C++ types do not require a</div><div class="line"><a name="l00645"></a><span class="lineno">  645</span>&#160;custom serializer.</div><div class="line"><a name="l00646"></a><span class="lineno">  646</span>&#160;</div><div class="line"><a name="l00647"></a><span class="lineno">  647</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00648"></a><span class="lineno">  648</span>&#160;</div><div class="line"><a name="l00649"></a><span class="lineno">  649</span>&#160;### xsd:string                                                           {#qt-1}</div><div class="line"><a name="l00650"></a><span class="lineno">  650</span>&#160;</div><div class="line"><a name="l00651"></a><span class="lineno">  651</span>&#160;To use Qt strings instead of C++ strings, add the following definition to</div><div class="line"><a name="l00652"></a><span class="lineno">  652</span>&#160;&lt;i&gt;`typemap.dat`&lt;/i&gt;:</div><div class="line"><a name="l00653"></a><span class="lineno">  653</span>&#160;</div><div class="line"><a name="l00654"></a><span class="lineno">  654</span>&#160;    xsd__string = #import &quot;custom/qstring.h&quot;</div><div class="line"><a name="l00655"></a><span class="lineno">  655</span>&#160;</div><div class="line"><a name="l00656"></a><span class="lineno">  656</span>&#160;After running wsdl2h and soapcpp2, compile &lt;i&gt;`gsoap/custom/qstring.cpp`&lt;/i&gt; with your</div><div class="line"><a name="l00657"></a><span class="lineno">  657</span>&#160;project.</div><div class="line"><a name="l00658"></a><span class="lineno">  658</span>&#160;</div><div class="line"><a name="l00659"></a><span class="lineno">  659</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00660"></a><span class="lineno">  660</span>&#160;</div><div class="line"><a name="l00661"></a><span class="lineno">  661</span>&#160;### xsd:base64Binary                                                     {#qt-2}</div><div class="line"><a name="l00662"></a><span class="lineno">  662</span>&#160;</div><div class="line"><a name="l00663"></a><span class="lineno">  663</span>&#160;To use Qt byte arrays for &lt;i&gt;`xsd:base64Binary`&lt;/i&gt; instead of the</div><div class="line"><a name="l00664"></a><span class="lineno">  664</span>&#160;`xsd__base64Binary` class, add the following definition to &lt;i&gt;`typemap.dat`&lt;/i&gt;:</div><div class="line"><a name="l00665"></a><span class="lineno">  665</span>&#160;</div><div class="line"><a name="l00666"></a><span class="lineno">  666</span>&#160;    xsd__base64Binary = #import &quot;custom/qbytearray_base64.h&quot;</div><div class="line"><a name="l00667"></a><span class="lineno">  667</span>&#160;</div><div class="line"><a name="l00668"></a><span class="lineno">  668</span>&#160;After running wsdl2h and soapcpp2, compile &lt;i&gt;`gsoap/custom/qbytearray_base64.cpp`&lt;/i&gt; with</div><div class="line"><a name="l00669"></a><span class="lineno">  669</span>&#160;your project.</div><div class="line"><a name="l00670"></a><span class="lineno">  670</span>&#160;</div><div class="line"><a name="l00671"></a><span class="lineno">  671</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00672"></a><span class="lineno">  672</span>&#160;</div><div class="line"><a name="l00673"></a><span class="lineno">  673</span>&#160;### xsd:hexBinary                                                        {#qt-3}</div><div class="line"><a name="l00674"></a><span class="lineno">  674</span>&#160;</div><div class="line"><a name="l00675"></a><span class="lineno">  675</span>&#160;To use Qt byte arrays for &lt;i&gt;`xsd:hexBinary`&lt;/i&gt; instead of the `xsd__base64Binary`</div><div class="line"><a name="l00676"></a><span class="lineno">  676</span>&#160;class, add the following definition to &lt;i&gt;`typemap.dat`&lt;/i&gt;:</div><div class="line"><a name="l00677"></a><span class="lineno">  677</span>&#160;</div><div class="line"><a name="l00678"></a><span class="lineno">  678</span>&#160;    xsd__hexBinary = #import &quot;custom/qbytearray_hex.h&quot;</div><div class="line"><a name="l00679"></a><span class="lineno">  679</span>&#160;</div><div class="line"><a name="l00680"></a><span class="lineno">  680</span>&#160;After running wsdl2h and soapcpp2, compile &lt;i&gt;`gsoap/custom/qbytearray_hex.cpp`&lt;/i&gt; with</div><div class="line"><a name="l00681"></a><span class="lineno">  681</span>&#160;your project.</div><div class="line"><a name="l00682"></a><span class="lineno">  682</span>&#160;</div><div class="line"><a name="l00683"></a><span class="lineno">  683</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00684"></a><span class="lineno">  684</span>&#160;</div><div class="line"><a name="l00685"></a><span class="lineno">  685</span>&#160;### xsd:dateTime                                                         {#qt-4}</div><div class="line"><a name="l00686"></a><span class="lineno">  686</span>&#160;</div><div class="line"><a name="l00687"></a><span class="lineno">  687</span>&#160;To use Qt QDateTime for &lt;i&gt;`xsd:dateTime`&lt;/i&gt;, add the following definition to</div><div class="line"><a name="l00688"></a><span class="lineno">  688</span>&#160;&lt;i&gt;`typemap.dat`&lt;/i&gt;:</div><div class="line"><a name="l00689"></a><span class="lineno">  689</span>&#160;</div><div class="line"><a name="l00690"></a><span class="lineno">  690</span>&#160;    xsd__dateTime = #import &quot;custom/datetime.h&quot;</div><div class="line"><a name="l00691"></a><span class="lineno">  691</span>&#160;</div><div class="line"><a name="l00692"></a><span class="lineno">  692</span>&#160;After running wsdl2h and soapcpp2, compile &lt;i&gt;`gsoap/custom/qdatetime.cpp`&lt;/i&gt; with</div><div class="line"><a name="l00693"></a><span class="lineno">  693</span>&#160;your project.</div><div class="line"><a name="l00694"></a><span class="lineno">  694</span>&#160;</div><div class="line"><a name="l00695"></a><span class="lineno">  695</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00696"></a><span class="lineno">  696</span>&#160;</div><div class="line"><a name="l00697"></a><span class="lineno">  697</span>&#160;### xsd:date                                                             {#qt-5}</div><div class="line"><a name="l00698"></a><span class="lineno">  698</span>&#160;</div><div class="line"><a name="l00699"></a><span class="lineno">  699</span>&#160;To use Qt QDate for &lt;i&gt;`xsd:date`&lt;/i&gt;, add the following definition to</div><div class="line"><a name="l00700"></a><span class="lineno">  700</span>&#160;&lt;i&gt;`typemap.dat`&lt;/i&gt;:</div><div class="line"><a name="l00701"></a><span class="lineno">  701</span>&#160;</div><div class="line"><a name="l00702"></a><span class="lineno">  702</span>&#160;    xsd__date = #import &quot;custom/qdate.h&quot;</div><div class="line"><a name="l00703"></a><span class="lineno">  703</span>&#160;</div><div class="line"><a name="l00704"></a><span class="lineno">  704</span>&#160;After running wsdl2h and soapcpp2, compile &lt;i&gt;`gsoap/custom/qdate.cpp`&lt;/i&gt; with your</div><div class="line"><a name="l00705"></a><span class="lineno">  705</span>&#160;project.</div><div class="line"><a name="l00706"></a><span class="lineno">  706</span>&#160;</div><div class="line"><a name="l00707"></a><span class="lineno">  707</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00708"></a><span class="lineno">  708</span>&#160;</div><div class="line"><a name="l00709"></a><span class="lineno">  709</span>&#160;### xsd:time                                                             {#qt-6}</div><div class="line"><a name="l00710"></a><span class="lineno">  710</span>&#160;</div><div class="line"><a name="l00711"></a><span class="lineno">  711</span>&#160;To use Qt QDate for &lt;i&gt;`xsd:time`&lt;/i&gt;, add the following definition to</div><div class="line"><a name="l00712"></a><span class="lineno">  712</span>&#160;&lt;i&gt;`typemap.dat`&lt;/i&gt;:</div><div class="line"><a name="l00713"></a><span class="lineno">  713</span>&#160;</div><div class="line"><a name="l00714"></a><span class="lineno">  714</span>&#160;    xsd__time = #import &quot;custom/qtime.h&quot;</div><div class="line"><a name="l00715"></a><span class="lineno">  715</span>&#160;</div><div class="line"><a name="l00716"></a><span class="lineno">  716</span>&#160;After running wsdl2h and soapcpp2, compile &lt;i&gt;`gsoap/custom/qtime.cpp`&lt;/i&gt; with your</div><div class="line"><a name="l00717"></a><span class="lineno">  717</span>&#160;project.</div><div class="line"><a name="l00718"></a><span class="lineno">  718</span>&#160;</div><div class="line"><a name="l00719"></a><span class="lineno">  719</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00720"></a><span class="lineno">  720</span>&#160;</div><div class="line"><a name="l00721"></a><span class="lineno">  721</span>&#160;Class/struct member additions                                        {#typemap3}</div><div class="line"><a name="l00722"></a><span class="lineno">  722</span>&#160;-----------------------------</div><div class="line"><a name="l00723"></a><span class="lineno">  723</span>&#160;</div><div class="line"><a name="l00724"></a><span class="lineno">  724</span>&#160;All generated classes and structs can be augmented with additional</div><div class="line"><a name="l00725"></a><span class="lineno">  725</span>&#160;members such as methods, constructors and destructors, and private members:</div><div class="line"><a name="l00726"></a><span class="lineno">  726</span>&#160;</div><div class="line"><a name="l00727"></a><span class="lineno">  727</span>&#160;    prefix__type = $ member-declaration</div><div class="line"><a name="l00728"></a><span class="lineno">  728</span>&#160;</div><div class="line"><a name="l00729"></a><span class="lineno">  729</span>&#160;For example, we can add method declarations and private members to a class, say</div><div class="line"><a name="l00730"></a><span class="lineno">  730</span>&#160;`ns__record` as follows:</div><div class="line"><a name="l00731"></a><span class="lineno">  731</span>&#160;</div><div class="line"><a name="l00732"></a><span class="lineno">  732</span>&#160;    ns__record = $ ns__record(const ns__record &amp;); // copy constructor</div><div class="line"><a name="l00733"></a><span class="lineno">  733</span>&#160;    ns__record = $ void print();                   // a print method</div><div class="line"><a name="l00734"></a><span class="lineno">  734</span>&#160;    ns__record = $ private: int status;            // a private member</div><div class="line"><a name="l00735"></a><span class="lineno">  735</span>&#160;</div><div class="line"><a name="l00736"></a><span class="lineno">  736</span>&#160;Method declarations cannot include any code, because soapcpp2&#39;s input permits</div><div class="line"><a name="l00737"></a><span class="lineno">  737</span>&#160;only type declarations, not code.</div><div class="line"><a name="l00738"></a><span class="lineno">  738</span>&#160;</div><div class="line"><a name="l00739"></a><span class="lineno">  739</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00740"></a><span class="lineno">  740</span>&#160;</div><div class="line"><a name="l00741"></a><span class="lineno">  741</span>&#160;Replacing XSD types by equivalent alternatives                       {#typemap4}</div><div class="line"><a name="l00742"></a><span class="lineno">  742</span>&#160;----------------------------------------------</div><div class="line"><a name="l00743"></a><span class="lineno">  743</span>&#160;</div><div class="line"><a name="l00744"></a><span class="lineno">  744</span>&#160;Type replacements can be given to replace one type entirely with another given</div><div class="line"><a name="l00745"></a><span class="lineno">  745</span>&#160;type:</div><div class="line"><a name="l00746"></a><span class="lineno">  746</span>&#160;</div><div class="line"><a name="l00747"></a><span class="lineno">  747</span>&#160;    prefix__type1 == prefix__type2</div><div class="line"><a name="l00748"></a><span class="lineno">  748</span>&#160;</div><div class="line"><a name="l00749"></a><span class="lineno">  749</span>&#160;This replaces all `prefix__type1` by `prefix__type2` in the wsdl2h output.</div><div class="line"><a name="l00750"></a><span class="lineno">  750</span>&#160;</div><div class="line"><a name="l00751"></a><span class="lineno">  751</span>&#160;@warning Do not agressively replace types, because this can cause XML schema</div><div class="line"><a name="l00752"></a><span class="lineno">  752</span>&#160;validation to fail when a value-type mismatch is encountered in the XML input.</div><div class="line"><a name="l00753"></a><span class="lineno">  753</span>&#160;Therefore, only replace similar types with other similar types that are wider</div><div class="line"><a name="l00754"></a><span class="lineno">  754</span>&#160;(e.g.  `short` by `int` and `float` by `double`).</div><div class="line"><a name="l00755"></a><span class="lineno">  755</span>&#160;</div><div class="line"><a name="l00756"></a><span class="lineno">  756</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00757"></a><span class="lineno">  757</span>&#160;</div><div class="line"><a name="l00758"></a><span class="lineno">  758</span>&#160;The special variables $CONTAINER, $POINTER, $SIZE and $OPTIONAL      {#typemap5}</div><div class="line"><a name="l00759"></a><span class="lineno">  759</span>&#160;---------------------------------------------------------------</div><div class="line"><a name="l00760"></a><span class="lineno">  760</span>&#160;</div><div class="line"><a name="l00761"></a><span class="lineno">  761</span>&#160;The &lt;i&gt;`typemap.dat`&lt;/i&gt; &lt;b&gt;`$CONTAINER`&lt;/b&gt; variable defines the container type to use in</div><div class="line"><a name="l00762"></a><span class="lineno">  762</span>&#160;the wsdl2h-generated declarations for C++, which is `std::vector` by default.</div><div class="line"><a name="l00763"></a><span class="lineno">  763</span>&#160;For example, to use `std::list` as the container in the wsdl2h-generated</div><div class="line"><a name="l00764"></a><span class="lineno">  764</span>&#160;declarations we add the following line to &lt;i&gt;`typemap.dat`&lt;/i&gt;:</div><div class="line"><a name="l00765"></a><span class="lineno">  765</span>&#160;</div><div class="line"><a name="l00766"></a><span class="lineno">  766</span>&#160;    $CONTAINER = std::list</div><div class="line"><a name="l00767"></a><span class="lineno">  767</span>&#160;</div><div class="line"><a name="l00768"></a><span class="lineno">  768</span>&#160;Also a Qt container can be used instead of the default `std::vector`, for</div><div class="line"><a name="l00769"></a><span class="lineno">  769</span>&#160;example `QVector`:</div><div class="line"><a name="l00770"></a><span class="lineno">  770</span>&#160;</div><div class="line"><a name="l00771"></a><span class="lineno">  771</span>&#160;    [</div><div class="line"><a name="l00772"></a><span class="lineno">  772</span>&#160;    #include &lt;QVector&gt;</div><div class="line"><a name="l00773"></a><span class="lineno">  773</span>&#160;    ]</div><div class="line"><a name="l00774"></a><span class="lineno">  774</span>&#160;    $CONTAINER = QVector</div><div class="line"><a name="l00775"></a><span class="lineno">  775</span>&#160;</div><div class="line"><a name="l00776"></a><span class="lineno">  776</span>&#160;To remove containers, use &lt;b&gt;`wsdl2h -s`&lt;/b&gt;.  This also removes `std::string`,</div><div class="line"><a name="l00777"></a><span class="lineno">  777</span>&#160;but you can re-introduce `std::string` with</div><div class="line"><a name="l00778"></a><span class="lineno">  778</span>&#160;&lt;b&gt;`xsd__string = | std::string`&lt;/b&gt; in &lt;i&gt;`typemap.dat`&lt;/i&gt;.</div><div class="line"><a name="l00779"></a><span class="lineno">  779</span>&#160;</div><div class="line"><a name="l00780"></a><span class="lineno">  780</span>&#160;The &lt;i&gt;`typemap.dat`&lt;/i&gt; &lt;b&gt;`$POINTER`&lt;/b&gt; variable defines the smart pointer to use in the</div><div class="line"><a name="l00781"></a><span class="lineno">  781</span>&#160;wsdl2h-generated declarations for C++, which replaces the use of `*` pointers.</div><div class="line"><a name="l00782"></a><span class="lineno">  782</span>&#160;For example:</div><div class="line"><a name="l00783"></a><span class="lineno">  783</span>&#160;</div><div class="line"><a name="l00784"></a><span class="lineno">  784</span>&#160;    $POINTER = std::shared_ptr</div><div class="line"><a name="l00785"></a><span class="lineno">  785</span>&#160;</div><div class="line"><a name="l00786"></a><span class="lineno">  786</span>&#160;Not all pointers in the generated output are replaced by smart pointers by</div><div class="line"><a name="l00787"></a><span class="lineno">  787</span>&#160;wsdl2h, such as pointers as union members and pointers as struct/class members</div><div class="line"><a name="l00788"></a><span class="lineno">  788</span>&#160;that point to arrays of values.</div><div class="line"><a name="l00789"></a><span class="lineno">  789</span>&#160;</div><div class="line"><a name="l00790"></a><span class="lineno">  790</span>&#160;@note The standard smart pointer `std::shared_ptr` is generally safe to use.</div><div class="line"><a name="l00791"></a><span class="lineno">  791</span>&#160;Other smart pointers such as `std::unique_ptr` and `std::auto_ptr` may cause</div><div class="line"><a name="l00792"></a><span class="lineno">  792</span>&#160;compile-time errors when classes have smart pointer members but no copy</div><div class="line"><a name="l00793"></a><span class="lineno">  793</span>&#160;constructor (a default copy constructor).  A copy constructor is required for</div><div class="line"><a name="l00794"></a><span class="lineno">  794</span>&#160;non-shared smart pointer copying or swapping.</div><div class="line"><a name="l00795"></a><span class="lineno">  795</span>&#160;</div><div class="line"><a name="l00796"></a><span class="lineno">  796</span>&#160;Alternatives to `std::shared_ptr` of the form `NAMESPACE::shared_ptr` can be</div><div class="line"><a name="l00797"></a><span class="lineno">  797</span>&#160;assigned to &lt;b&gt;`$POINTER`&lt;/b&gt; when the namespace `NAMESPACE` also implements</div><div class="line"><a name="l00798"></a><span class="lineno">  798</span>&#160;`NAMESPACE::make_shared` and when the shared pointer class provides `reset()`</div><div class="line"><a name="l00799"></a><span class="lineno">  799</span>&#160;and`get()` methods and the dereference operator.  For example Boost</div><div class="line"><a name="l00800"></a><span class="lineno">  800</span>&#160;`boost::shared_ptr`:</div><div class="line"><a name="l00801"></a><span class="lineno">  801</span>&#160;</div><div class="line"><a name="l00802"></a><span class="lineno">  802</span>&#160;    [</div><div class="line"><a name="l00803"></a><span class="lineno">  803</span>&#160;    #include &lt;boost/shared_ptr.hpp&gt;</div><div class="line"><a name="l00804"></a><span class="lineno">  804</span>&#160;    ]</div><div class="line"><a name="l00805"></a><span class="lineno">  805</span>&#160;    $POINTER = boost::shared_ptr</div><div class="line"><a name="l00806"></a><span class="lineno">  806</span>&#160;</div><div class="line"><a name="l00807"></a><span class="lineno">  807</span>&#160;The user-defined content between &lt;b&gt;`[`&lt;/b&gt; and &lt;b&gt;`]`&lt;/b&gt; ensures that we include the Boost</div><div class="line"><a name="l00808"></a><span class="lineno">  808</span>&#160;header files that are needed to support `boost::shared_ptr` and</div><div class="line"><a name="l00809"></a><span class="lineno">  809</span>&#160;`boost::make_shared`.</div><div class="line"><a name="l00810"></a><span class="lineno">  810</span>&#160;</div><div class="line"><a name="l00811"></a><span class="lineno">  811</span>&#160;The variable &lt;b&gt;`$SIZE`&lt;/b&gt; defines the type of array sizes, which is `int` by</div><div class="line"><a name="l00812"></a><span class="lineno">  812</span>&#160;default.  For example, to change array size types to `size_t`:</div><div class="line"><a name="l00813"></a><span class="lineno">  813</span>&#160;</div><div class="line"><a name="l00814"></a><span class="lineno">  814</span>&#160;    $SIZE = size_t</div><div class="line"><a name="l00815"></a><span class="lineno">  815</span>&#160;</div><div class="line"><a name="l00816"></a><span class="lineno">  816</span>&#160;Permissible types are `int` and `size_t`.  This variable does not affect the</div><div class="line"><a name="l00817"></a><span class="lineno">  817</span>&#160;size of dynamic arrays, `xsd__hexBinary` and `xsd__base64Binary` types, which</div><div class="line"><a name="l00818"></a><span class="lineno">  818</span>&#160;is always `int`.</div><div class="line"><a name="l00819"></a><span class="lineno">  819</span>&#160;</div><div class="line"><a name="l00820"></a><span class="lineno">  820</span>&#160;When C++17 is enabled with wsdl2h and soapcpp2 option &lt;b&gt;`-c++17`&lt;/b&gt;, you can</div><div class="line"><a name="l00821"></a><span class="lineno">  821</span>&#160;also semi-automatically enable `std::optional` declarations with optional class</div><div class="line"><a name="l00822"></a><span class="lineno">  822</span>&#160;and structure member variables.  This means that `std::optional` is used</div><div class="line"><a name="l00823"></a><span class="lineno">  823</span>&#160;instead of a (smart) pointer to make a member optional.</div><div class="line"><a name="l00824"></a><span class="lineno">  824</span>&#160;</div><div class="line"><a name="l00825"></a><span class="lineno">  825</span>&#160;To enable `std::optional` with member variables that are primitive types,</div><div class="line"><a name="l00826"></a><span class="lineno">  826</span>&#160;`typedef`, and `enum` automatically:</div><div class="line"><a name="l00827"></a><span class="lineno">  827</span>&#160;</div><div class="line"><a name="l00828"></a><span class="lineno">  828</span>&#160;    $OPTIONAL = std::optional</div><div class="line"><a name="l00829"></a><span class="lineno">  829</span>&#160;</div><div class="line"><a name="l00830"></a><span class="lineno">  830</span>&#160;Local unnamed simpleType restrictions may not adopt the specified optional type</div><div class="line"><a name="l00831"></a><span class="lineno">  831</span>&#160;and still use pointers instead.  This limitation may be lifted in a future</div><div class="line"><a name="l00832"></a><span class="lineno">  832</span>&#160;release.</div><div class="line"><a name="l00833"></a><span class="lineno">  833</span>&#160;</div><div class="line"><a name="l00834"></a><span class="lineno">  834</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00835"></a><span class="lineno">  835</span>&#160;</div><div class="line"><a name="l00836"></a><span class="lineno">  836</span>&#160;User-defined content                                                 {#typemap6}</div><div class="line"><a name="l00837"></a><span class="lineno">  837</span>&#160;--------------------</div><div class="line"><a name="l00838"></a><span class="lineno">  838</span>&#160;</div><div class="line"><a name="l00839"></a><span class="lineno">  839</span>&#160;Any other content to be generated by wsdl2h can be included in &lt;i&gt;`typemap.dat`&lt;/i&gt; by</div><div class="line"><a name="l00840"></a><span class="lineno">  840</span>&#160;enclosing it within brackets &lt;b&gt;`[`&lt;/b&gt; and &lt;b&gt;`]`&lt;/b&gt; anywhere in the &lt;i&gt;`typemap.dat`&lt;/i&gt; file.</div><div class="line"><a name="l00841"></a><span class="lineno">  841</span>&#160;Each of the two brackets must appear at the start of a new line.</div><div class="line"><a name="l00842"></a><span class="lineno">  842</span>&#160;</div><div class="line"><a name="l00843"></a><span class="lineno">  843</span>&#160;For example, we can add an `#import &quot;wsa5.h&quot;` to the wsdl2h-generated output as</div><div class="line"><a name="l00844"></a><span class="lineno">  844</span>&#160;follows:</div><div class="line"><a name="l00845"></a><span class="lineno">  845</span>&#160;</div><div class="line"><a name="l00846"></a><span class="lineno">  846</span>&#160;    [</div><div class="line"><a name="l00847"></a><span class="lineno">  847</span>&#160;    #import &quot;import/wsa5.h&quot;</div><div class="line"><a name="l00848"></a><span class="lineno">  848</span>&#160;    ]</div><div class="line"><a name="l00849"></a><span class="lineno">  849</span>&#160;</div><div class="line"><a name="l00850"></a><span class="lineno">  850</span>&#160;which emits the `#import &quot;import/wsa5.h&quot;` literally at the start of the</div><div class="line"><a name="l00851"></a><span class="lineno">  851</span>&#160;wsdl2h-generated header file.</div><div class="line"><a name="l00852"></a><span class="lineno">  852</span>&#160;</div><div class="line"><a name="l00853"></a><span class="lineno">  853</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00854"></a><span class="lineno">  854</span>&#160;</div><div class="line"><a name="l00855"></a><span class="lineno">  855</span>&#160;Mapping C/C++ to XML schema                                             {#toxsd}</div><div class="line"><a name="l00856"></a><span class="lineno">  856</span>&#160;===========================</div><div class="line"><a name="l00857"></a><span class="lineno">  857</span>&#160;</div><div class="line"><a name="l00858"></a><span class="lineno">  858</span>&#160;The soapcpp2 command generates the data binding implementation code from a data</div><div class="line"><a name="l00859"></a><span class="lineno">  859</span>&#160;binding interface &lt;i&gt;`file.h`&lt;/i&gt;:</div><div class="line"><a name="l00860"></a><span class="lineno">  860</span>&#160;</div><div class="line"><a name="l00861"></a><span class="lineno">  861</span>&#160;    soapcpp2 [options] file.h</div><div class="line"><a name="l00862"></a><span class="lineno">  862</span>&#160;</div><div class="line"><a name="l00863"></a><span class="lineno">  863</span>&#160;where &lt;i&gt;`file.h`&lt;/i&gt; is a interface header file that declares the XML data</div><div class="line"><a name="l00864"></a><span class="lineno">  864</span>&#160;binding interface.  The &lt;i&gt;`file.h`&lt;/i&gt; is typically generated by wsdl2h, but</div><div class="line"><a name="l00865"></a><span class="lineno">  865</span>&#160;you can also declare one yourself.  If so, add `//gsoap`</div><div class="line"><a name="l00866"></a><span class="lineno">  866</span>&#160;[directives](#directives) and declare in this file all our C/C++ types you want</div><div class="line"><a name="l00867"></a><span class="lineno">  867</span>&#160;to serialize in XML.</div><div class="line"><a name="l00868"></a><span class="lineno">  868</span>&#160;</div><div class="line"><a name="l00869"></a><span class="lineno">  869</span>&#160;You can also declare functions that will be converted to Web service operations</div><div class="line"><a name="l00870"></a><span class="lineno">  870</span>&#160;by soapcpp2.  Global function declarations define service operations, which are</div><div class="line"><a name="l00871"></a><span class="lineno">  871</span>&#160;of the form:</div><div class="line"><a name="l00872"></a><span class="lineno">  872</span>&#160;</div><div class="line"><a name="l00873"></a><span class="lineno">  873</span>&#160;~~~{.cpp}</div><div class="line"><a name="l00874"></a><span class="lineno">  874</span>&#160;    int prefix__func(arg1, arg2, ..., argn, result);</div><div class="line"><a name="l00875"></a><span class="lineno">  875</span>&#160;~~~</div><div class="line"><a name="l00876"></a><span class="lineno">  876</span>&#160;</div><div class="line"><a name="l00877"></a><span class="lineno">  877</span>&#160;where `arg1`, `arg2`, ..., `argn` are formal argument declarations of the input</div><div class="line"><a name="l00878"></a><span class="lineno">  878</span>&#160;and `result` is a formal argument for the output, which must be a pointer or</div><div class="line"><a name="l00879"></a><span class="lineno">  879</span>&#160;reference to the result object to be populated.  More information on declaring</div><div class="line"><a name="l00880"></a><span class="lineno">  880</span>&#160;and implementing service operation functions can be found in the</div><div class="line"><a name="l00881"></a><span class="lineno">  881</span>&#160;[gSOAP user guide.](../../guide/html/index.html)</div><div class="line"><a name="l00882"></a><span class="lineno">  882</span>&#160;</div><div class="line"><a name="l00883"></a><span class="lineno">  883</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00884"></a><span class="lineno">  884</span>&#160;</div><div class="line"><a name="l00885"></a><span class="lineno">  885</span>&#160;Overview of serializable C/C++ types                                   {#toxsd1}</div><div class="line"><a name="l00886"></a><span class="lineno">  886</span>&#160;------------------------------------</div><div class="line"><a name="l00887"></a><span class="lineno">  887</span>&#160;</div><div class="line"><a name="l00888"></a><span class="lineno">  888</span>&#160;The following C/C++ types are supported by soapcpp2 and mapped to XSD types</div><div class="line"><a name="l00889"></a><span class="lineno">  889</span>&#160;and constructs.  See the subsections below for more details or follow the links.</div><div class="line"><a name="l00890"></a><span class="lineno">  890</span>&#160;</div><div class="line"><a name="l00891"></a><span class="lineno">  891</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00892"></a><span class="lineno">  892</span>&#160;</div><div class="line"><a name="l00893"></a><span class="lineno">  893</span>&#160;### List of Boolean types</div><div class="line"><a name="l00894"></a><span class="lineno">  894</span>&#160;</div><div class="line"><a name="l00895"></a><span class="lineno">  895</span>&#160;Boolean Type                  | Notes</div><div class="line"><a name="l00896"></a><span class="lineno">  896</span>&#160;----------------------------- | -----</div><div class="line"><a name="l00897"></a><span class="lineno">  897</span>&#160;`bool`                        | C++ bool</div><div class="line"><a name="l00898"></a><span class="lineno">  898</span>&#160;`enum xsd__boolean`           | C alternative to C++ `bool` with `false_` and `true_`</div><div class="line"><a name="l00899"></a><span class="lineno">  899</span>&#160; </div><div class="line"><a name="l00900"></a><span class="lineno">  900</span>&#160;@see Section [C++ bool and C alternative](#toxsd3).</div><div class="line"><a name="l00901"></a><span class="lineno">  901</span>&#160;</div><div class="line"><a name="l00902"></a><span class="lineno">  902</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00903"></a><span class="lineno">  903</span>&#160;</div><div class="line"><a name="l00904"></a><span class="lineno">  904</span>&#160;### List of enumeration and bitmask types</div><div class="line"><a name="l00905"></a><span class="lineno">  905</span>&#160;</div><div class="line"><a name="l00906"></a><span class="lineno">  906</span>&#160;Enumeration Type              | Notes</div><div class="line"><a name="l00907"></a><span class="lineno">  907</span>&#160;----------------------------- | -----</div><div class="line"><a name="l00908"></a><span class="lineno">  908</span>&#160;`enum`                        | enumeration</div><div class="line"><a name="l00909"></a><span class="lineno">  909</span>&#160;`enum class`                  | C++11 scoped enumeration, requires `soapcpp2 -c++11`</div><div class="line"><a name="l00910"></a><span class="lineno">  910</span>&#160;`enum*`                       | a bitmask that enumerates values 1, 2, 4, 8, ...</div><div class="line"><a name="l00911"></a><span class="lineno">  911</span>&#160;`enum* class`                 | C++11 scoped enumeration bitmask, requires `soapcpp2 -c++11`</div><div class="line"><a name="l00912"></a><span class="lineno">  912</span>&#160;</div><div class="line"><a name="l00913"></a><span class="lineno">  913</span>&#160;@see Section [enumerations and bitmasks](#toxsd4).</div><div class="line"><a name="l00914"></a><span class="lineno">  914</span>&#160;</div><div class="line"><a name="l00915"></a><span class="lineno">  915</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00916"></a><span class="lineno">  916</span>&#160;</div><div class="line"><a name="l00917"></a><span class="lineno">  917</span>&#160;### List of numerical types</div><div class="line"><a name="l00918"></a><span class="lineno">  918</span>&#160;</div><div class="line"><a name="l00919"></a><span class="lineno">  919</span>&#160;Numerical Type                | Notes</div><div class="line"><a name="l00920"></a><span class="lineno">  920</span>&#160;----------------------------- | -----</div><div class="line"><a name="l00921"></a><span class="lineno">  921</span>&#160;`char`                        | byte</div><div class="line"><a name="l00922"></a><span class="lineno">  922</span>&#160;`short`                       | 16 bit integer</div><div class="line"><a name="l00923"></a><span class="lineno">  923</span>&#160;`int`                         | 32 bit integer</div><div class="line"><a name="l00924"></a><span class="lineno">  924</span>&#160;`long`                        | 32 bit integer</div><div class="line"><a name="l00925"></a><span class="lineno">  925</span>&#160;`LONG64`                      | 64 bit integer</div><div class="line"><a name="l00926"></a><span class="lineno">  926</span>&#160;`xsd__integer`                | 128 bit integer, use `#import &quot;custom/int128.h&quot;`</div><div class="line"><a name="l00927"></a><span class="lineno">  927</span>&#160;`long long`                   | same as `LONG64`</div><div class="line"><a name="l00928"></a><span class="lineno">  928</span>&#160;`unsigned char`               | unsigned byte</div><div class="line"><a name="l00929"></a><span class="lineno">  929</span>&#160;`unsigned short`              | unsigned 16 bit integer</div><div class="line"><a name="l00930"></a><span class="lineno">  930</span>&#160;`unsigned int`                | unsigned 32 bit integer</div><div class="line"><a name="l00931"></a><span class="lineno">  931</span>&#160;`unsigned long`               | unsigned 32 bit integer</div><div class="line"><a name="l00932"></a><span class="lineno">  932</span>&#160;`ULONG64`                     | unsigned 64 bit integer</div><div class="line"><a name="l00933"></a><span class="lineno">  933</span>&#160;`unsigned long long`          | same as `ULONG64`</div><div class="line"><a name="l00934"></a><span class="lineno">  934</span>&#160;`int8_t`                      | same as `char`</div><div class="line"><a name="l00935"></a><span class="lineno">  935</span>&#160;`int16_t`                     | same as `short`</div><div class="line"><a name="l00936"></a><span class="lineno">  936</span>&#160;`int32_t`                     | same as `int`</div><div class="line"><a name="l00937"></a><span class="lineno">  937</span>&#160;`int64_t`                     | same as `LONG64`</div><div class="line"><a name="l00938"></a><span class="lineno">  938</span>&#160;`uint8_t`                     | same as `unsigned char`</div><div class="line"><a name="l00939"></a><span class="lineno">  939</span>&#160;`uint16_t`                    | same as `unsigned short`</div><div class="line"><a name="l00940"></a><span class="lineno">  940</span>&#160;`uint32_t`                    | same as `unsigned int`</div><div class="line"><a name="l00941"></a><span class="lineno">  941</span>&#160;`uint64_t`                    | same as `ULONG64`</div><div class="line"><a name="l00942"></a><span class="lineno">  942</span>&#160;`size_t`                      | transient type (not serializable)</div><div class="line"><a name="l00943"></a><span class="lineno">  943</span>&#160;`float`                       | 32 bit float</div><div class="line"><a name="l00944"></a><span class="lineno">  944</span>&#160;`double`                      | 64 bit float</div><div class="line"><a name="l00945"></a><span class="lineno">  945</span>&#160;`long double`                 | extended precision float, use `#import &quot;custom/long_double.h&quot;`</div><div class="line"><a name="l00946"></a><span class="lineno">  946</span>&#160;`xsd__decimal`                | `quadmath.h` library 128 bit quadruple precision float, use `#import &quot;custom/float128.h&quot;`</div><div class="line"><a name="l00947"></a><span class="lineno">  947</span>&#160;`typedef`                     | declares a type name, with optional value range and string length bounds</div><div class="line"><a name="l00948"></a><span class="lineno">  948</span>&#160;</div><div class="line"><a name="l00949"></a><span class="lineno">  949</span>&#160;@see Section [numerical types](#toxsd5).</div><div class="line"><a name="l00950"></a><span class="lineno">  950</span>&#160;</div><div class="line"><a name="l00951"></a><span class="lineno">  951</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00952"></a><span class="lineno">  952</span>&#160;</div><div class="line"><a name="l00953"></a><span class="lineno">  953</span>&#160;### List of string types</div><div class="line"><a name="l00954"></a><span class="lineno">  954</span>&#160;</div><div class="line"><a name="l00955"></a><span class="lineno">  955</span>&#160;String Type                   | Notes</div><div class="line"><a name="l00956"></a><span class="lineno">  956</span>&#160;----------------------------- | -----</div><div class="line"><a name="l00957"></a><span class="lineno">  957</span>&#160;`char*`                       | string (may contain UTF-8 with flag `SOAP_C_UTFSTRING`)</div><div class="line"><a name="l00958"></a><span class="lineno">  958</span>&#160;`wchar_t*`                    | wide string</div><div class="line"><a name="l00959"></a><span class="lineno">  959</span>&#160;`std::string`                 | C++ string (may contain UTF-8 with flag `SOAP_C_UTFSTRING`)</div><div class="line"><a name="l00960"></a><span class="lineno">  960</span>&#160;`std::wstring`                | C++ wide string</div><div class="line"><a name="l00961"></a><span class="lineno">  961</span>&#160;`char[N]`                     | fixed-size string, requires `soapcpp2 -b`</div><div class="line"><a name="l00962"></a><span class="lineno">  962</span>&#160;`_QName`                      | normalized QName content</div><div class="line"><a name="l00963"></a><span class="lineno">  963</span>&#160;`_XML`                        | literal XML string content with wide characters in UTF-8</div><div class="line"><a name="l00964"></a><span class="lineno">  964</span>&#160;`typedef`                     | declares a new string type name, may restrict string length</div><div class="line"><a name="l00965"></a><span class="lineno">  965</span>&#160;</div><div class="line"><a name="l00966"></a><span class="lineno">  966</span>&#160;@see Section [string types](#toxsd6).</div><div class="line"><a name="l00967"></a><span class="lineno">  967</span>&#160;</div><div class="line"><a name="l00968"></a><span class="lineno">  968</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00969"></a><span class="lineno">  969</span>&#160;</div><div class="line"><a name="l00970"></a><span class="lineno">  970</span>&#160;### List of date and time types</div><div class="line"><a name="l00971"></a><span class="lineno">  971</span>&#160;</div><div class="line"><a name="l00972"></a><span class="lineno">  972</span>&#160;Date and Time Type                      | Notes</div><div class="line"><a name="l00973"></a><span class="lineno">  973</span>&#160;--------------------------------------- | -----</div><div class="line"><a name="l00974"></a><span class="lineno">  974</span>&#160;`time_t`                                | date and time point since epoch</div><div class="line"><a name="l00975"></a><span class="lineno">  975</span>&#160;`struct tm`                             | date and time point, use `#import &quot;custom/struct_tm.h&quot;`</div><div class="line"><a name="l00976"></a><span class="lineno">  976</span>&#160;`struct tm`                             | date point, use `#import &quot;custom/struct_tm_date.h&quot;`</div><div class="line"><a name="l00977"></a><span class="lineno">  977</span>&#160;`struct timeval`                        | date and time point, use `#import &quot;custom/struct_timeval.h&quot;`</div><div class="line"><a name="l00978"></a><span class="lineno">  978</span>&#160;`unsigned long long`                    | time point in microseconds, use `#import &quot;custom/long_time.h&quot;`</div><div class="line"><a name="l00979"></a><span class="lineno">  979</span>&#160;`std::chrono::system_clock::time_point` | date and time point, use `#import &quot;custom/chrono_time_point.h&quot;`</div><div class="line"><a name="l00980"></a><span class="lineno">  980</span>&#160;</div><div class="line"><a name="l00981"></a><span class="lineno">  981</span>&#160;@see Section [date and time types](#toxsd7).</div><div class="line"><a name="l00982"></a><span class="lineno">  982</span>&#160;</div><div class="line"><a name="l00983"></a><span class="lineno">  983</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00984"></a><span class="lineno">  984</span>&#160;</div><div class="line"><a name="l00985"></a><span class="lineno">  985</span>&#160;### List of time duration types</div><div class="line"><a name="l00986"></a><span class="lineno">  986</span>&#160;</div><div class="line"><a name="l00987"></a><span class="lineno">  987</span>&#160;Time Duration Type            | Notes</div><div class="line"><a name="l00988"></a><span class="lineno">  988</span>&#160;----------------------------- | -----</div><div class="line"><a name="l00989"></a><span class="lineno">  989</span>&#160;`long long`                   | duration in milliseconds, use `#import &quot;custom/duration.h&quot;`</div><div class="line"><a name="l00990"></a><span class="lineno">  990</span>&#160;`std::chrono::nanoseconds`    | duration in nanoseconds, use `#import &quot;custom/chrono_duration.h&quot;`</div><div class="line"><a name="l00991"></a><span class="lineno">  991</span>&#160;</div><div class="line"><a name="l00992"></a><span class="lineno">  992</span>&#160;@see Section [time duration types](#toxsd8).</div><div class="line"><a name="l00993"></a><span class="lineno">  993</span>&#160;</div><div class="line"><a name="l00994"></a><span class="lineno">  994</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l00995"></a><span class="lineno">  995</span>&#160;</div><div class="line"><a name="l00996"></a><span class="lineno">  996</span>&#160;### List of classes, structs, unions, pointers, containers, and arrays</div><div class="line"><a name="l00997"></a><span class="lineno">  997</span>&#160;</div><div class="line"><a name="l00998"></a><span class="lineno">  998</span>&#160;Classes, Structs, and Members | Notes</div><div class="line"><a name="l00999"></a><span class="lineno">  999</span>&#160;----------------------------- | -----</div><div class="line"><a name="l01000"></a><span class="lineno"> 1000</span>&#160;`class`                       | C++ class with single inheritance only</div><div class="line"><a name="l01001"></a><span class="lineno"> 1001</span>&#160;`struct`                      | C struct or C++ struct without inheritance</div><div class="line"><a name="l01002"></a><span class="lineno"> 1002</span>&#160;`std::shared_ptr&lt;T&gt;`          | C++11 smart shared pointer</div><div class="line"><a name="l01003"></a><span class="lineno"> 1003</span>&#160;`std::unique_ptr&lt;T&gt;`          | C++11 smart pointer</div><div class="line"><a name="l01004"></a><span class="lineno"> 1004</span>&#160;`std::auto_ptr&lt;T&gt;`            | C++ smart pointer</div><div class="line"><a name="l01005"></a><span class="lineno"> 1005</span>&#160;`std::deque&lt;T&gt;`               | use `#import &quot;import/stldeque.h&quot;`</div><div class="line"><a name="l01006"></a><span class="lineno"> 1006</span>&#160;`std::list&lt;T&gt;`                | use `#import &quot;import/stllist.h&quot;`</div><div class="line"><a name="l01007"></a><span class="lineno"> 1007</span>&#160;`std::vector&lt;T&gt;`              | use `#import &quot;import/stlvector.h&quot;`</div><div class="line"><a name="l01008"></a><span class="lineno"> 1008</span>&#160;`std::set&lt;T&gt;`                 | use `#import &quot;import/stlset.h&quot;`</div><div class="line"><a name="l01009"></a><span class="lineno"> 1009</span>&#160;`template&lt;T&gt; class`           | a container with `begin()`, `end()`, `size()`, `clear()`, and `insert()` methods</div><div class="line"><a name="l01010"></a><span class="lineno"> 1010</span>&#160;`T*`                          | pointer to data of type `T`</div><div class="line"><a name="l01011"></a><span class="lineno"> 1011</span>&#160;`T*`                          | as a class or struct member: points to data of type `T` or array of `T` with member `__size`</div><div class="line"><a name="l01012"></a><span class="lineno"> 1012</span>&#160;`T[N]`                        | as a class or struct member: fixed-size array of type `T`</div><div class="line"><a name="l01013"></a><span class="lineno"> 1013</span>&#160;`union`                       | as a class or struct member: requires a variant selector member `__union`</div><div class="line"><a name="l01014"></a><span class="lineno"> 1014</span>&#160;`void*`                       | as a class or struct member: requires a `__type` member to indicate the type of object pointed to</div><div class="line"><a name="l01015"></a><span class="lineno"> 1015</span>&#160;</div><div class="line"><a name="l01016"></a><span class="lineno"> 1016</span>&#160;@see Section [classes and structs](#toxsd9).</div><div class="line"><a name="l01017"></a><span class="lineno"> 1017</span>&#160;</div><div class="line"><a name="l01018"></a><span class="lineno"> 1018</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l01019"></a><span class="lineno"> 1019</span>&#160;</div><div class="line"><a name="l01020"></a><span class="lineno"> 1020</span>&#160;### List of special classes and structs</div><div class="line"><a name="l01021"></a><span class="lineno"> 1021</span>&#160;</div><div class="line"><a name="l01022"></a><span class="lineno"> 1022</span>&#160;Special Classes and Structs   | Notes</div><div class="line"><a name="l01023"></a><span class="lineno"> 1023</span>&#160;----------------------------- | -----</div><div class="line"><a name="l01024"></a><span class="lineno"> 1024</span>&#160;Special Array class/struct    | single and multidimensional SOAP Arrays</div><div class="line"><a name="l01025"></a><span class="lineno"> 1025</span>&#160;Special Wrapper class/struct  | complexTypes with simpleContent, wraps `__item` member</div><div class="line"><a name="l01026"></a><span class="lineno"> 1026</span>&#160;`xsd__hexBinary`              | binary content</div><div class="line"><a name="l01027"></a><span class="lineno"> 1027</span>&#160;`xsd__base64Binary`           | binary content and optional DIME/MIME/MTOM attachments</div><div class="line"><a name="l01028"></a><span class="lineno"> 1028</span>&#160;`xsd__anyType`                | DOM elements, use `#import &quot;dom.h&quot;`</div><div class="line"><a name="l01029"></a><span class="lineno"> 1029</span>&#160;`@xsd__anyAttribute`          | DOM attributes, use `#import &quot;dom.h&quot;`</div><div class="line"><a name="l01030"></a><span class="lineno"> 1030</span>&#160;</div><div class="line"><a name="l01031"></a><span class="lineno"> 1031</span>&#160;@see Section [special classes and structs](#toxsd10).</div><div class="line"><a name="l01032"></a><span class="lineno"> 1032</span>&#160;</div><div class="line"><a name="l01033"></a><span class="lineno"> 1033</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l01034"></a><span class="lineno"> 1034</span>&#160;</div><div class="line"><a name="l01035"></a><span class="lineno"> 1035</span>&#160;Colon notation versus name prefixing with XML tag name translation     {#toxsd2}</div><div class="line"><a name="l01036"></a><span class="lineno"> 1036</span>&#160;------------------------------------------------------------------</div><div class="line"><a name="l01037"></a><span class="lineno"> 1037</span>&#160;</div><div class="line"><a name="l01038"></a><span class="lineno"> 1038</span>&#160;To bind C/C++ type names to XSD types, a simple form of name prefixing is used</div><div class="line"><a name="l01039"></a><span class="lineno"> 1039</span>&#160;by the gSOAP tools by prepending the XML namespace prefix to the C/C++ type</div><div class="line"><a name="l01040"></a><span class="lineno"> 1040</span>&#160;name with a pair of undescrores.  This also ensures that name clashes cannot</div><div class="line"><a name="l01041"></a><span class="lineno"> 1041</span>&#160;occur when multiple WSDL and XSD files are converted to C/C++.  Also, C++</div><div class="line"><a name="l01042"></a><span class="lineno"> 1042</span>&#160;namespaces are not sufficiently rich to capture XML schema namespaces</div><div class="line"><a name="l01043"></a><span class="lineno"> 1043</span>&#160;accurately, for example when class members are associated with schema elements</div><div class="line"><a name="l01044"></a><span class="lineno"> 1044</span>&#160;defined in another XML namespace and thus the XML namespace scope of the</div><div class="line"><a name="l01045"></a><span class="lineno"> 1045</span>&#160;member&#39;s name is relevant, not just its type.</div><div class="line"><a name="l01046"></a><span class="lineno"> 1046</span>&#160;</div><div class="line"><a name="l01047"></a><span class="lineno"> 1047</span>&#160;However, from a C/C++ centric point of view this can be cumbersome.  Therefore,</div><div class="line"><a name="l01048"></a><span class="lineno"> 1048</span>&#160;colon notation is an alternative to physically augmenting C/C++ names with</div><div class="line"><a name="l01049"></a><span class="lineno"> 1049</span>&#160;prefixes.</div><div class="line"><a name="l01050"></a><span class="lineno"> 1050</span>&#160;</div><div class="line"><a name="l01051"></a><span class="lineno"> 1051</span>&#160;For example, the following class uses colon notation to bind the `record` class</div><div class="line"><a name="l01052"></a><span class="lineno"> 1052</span>&#160;to the &lt;i&gt;`urn:types`&lt;/i&gt; schema:</div><div class="line"><a name="l01053"></a><span class="lineno"> 1053</span>&#160;</div><div class="line"><a name="l01054"></a><span class="lineno"> 1054</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01055"></a><span class="lineno"> 1055</span>&#160;    //gsoap ns schema namespace: urn:types</div><div class="line"><a name="l01056"></a><span class="lineno"> 1056</span>&#160;    class ns:record        // binding &#39;ns:&#39; to a type name</div><div class="line"><a name="l01057"></a><span class="lineno"> 1057</span>&#160;    {</div><div class="line"><a name="l01058"></a><span class="lineno"> 1058</span>&#160;     public:</div><div class="line"><a name="l01059"></a><span class="lineno"> 1059</span>&#160;        std::string name;</div><div class="line"><a name="l01060"></a><span class="lineno"> 1060</span>&#160;        uint64_t    SSN;</div><div class="line"><a name="l01061"></a><span class="lineno"> 1061</span>&#160;        ns:record   *spouse; // using &#39;ns:&#39; with the type name</div><div class="line"><a name="l01062"></a><span class="lineno"> 1062</span>&#160;        ns:record();         // using &#39;ns:&#39; here too</div><div class="line"><a name="l01063"></a><span class="lineno"> 1063</span>&#160;        ~ns:record();        // and here</div><div class="line"><a name="l01064"></a><span class="lineno"> 1064</span>&#160;    };</div><div class="line"><a name="l01065"></a><span class="lineno"> 1065</span>&#160;~~~</div><div class="line"><a name="l01066"></a><span class="lineno"> 1066</span>&#160;</div><div class="line"><a name="l01067"></a><span class="lineno"> 1067</span>&#160;The colon notation is stripped away by soapcpp2 when generating the data</div><div class="line"><a name="l01068"></a><span class="lineno"> 1068</span>&#160;binding implementation code for our project.  So the final code just uses</div><div class="line"><a name="l01069"></a><span class="lineno"> 1069</span>&#160;`record` to identify this class and its constructor/destructor.</div><div class="line"><a name="l01070"></a><span class="lineno"> 1070</span>&#160;</div><div class="line"><a name="l01071"></a><span class="lineno"> 1071</span>&#160;When using colon notation make sure to be consistent and not use colon notation</div><div class="line"><a name="l01072"></a><span class="lineno"> 1072</span>&#160;mixed with prefixed forms.  The qualified name `ns:record` differs from `ns__record`,</div><div class="line"><a name="l01073"></a><span class="lineno"> 1073</span>&#160;because `ns:record` is compiled to an unqualified `record` name in the source</div><div class="line"><a name="l01074"></a><span class="lineno"> 1074</span>&#160;code output by the soapcpp2 tool.</div><div class="line"><a name="l01075"></a><span class="lineno"> 1075</span>&#160;</div><div class="line"><a name="l01076"></a><span class="lineno"> 1076</span>&#160;Colon notation also facilitates overruling the elementFormDefault and</div><div class="line"><a name="l01077"></a><span class="lineno"> 1077</span>&#160;attributeFormDefault declaration that is applied to local elements and</div><div class="line"><a name="l01078"></a><span class="lineno"> 1078</span>&#160;attributes, when declared as members of classes, structs, and unions.  For more</div><div class="line"><a name="l01079"></a><span class="lineno"> 1079</span>&#160;details, see [qualified and unqualified members](#toxsd9-6).</div><div class="line"><a name="l01080"></a><span class="lineno"> 1080</span>&#160;</div><div class="line"><a name="l01081"></a><span class="lineno"> 1081</span>&#160;A C/C++ identifier name (a type name, member name, function name, or parameter</div><div class="line"><a name="l01082"></a><span class="lineno"> 1082</span>&#160;name) is translated to an XML tag name by the following rules:</div><div class="line"><a name="l01083"></a><span class="lineno"> 1083</span>&#160;</div><div class="line"><a name="l01084"></a><span class="lineno"> 1084</span>&#160;- Two leading underscores indicates that the identifier name has no XML tag</div><div class="line"><a name="l01085"></a><span class="lineno"> 1085</span>&#160;  name, i.e. this name is not visible in XML and is not translated.</div><div class="line"><a name="l01086"></a><span class="lineno"> 1086</span>&#160;</div><div class="line"><a name="l01087"></a><span class="lineno"> 1087</span>&#160;- A leading underscore is removed, but the underscore indicates that: **a**) a</div><div class="line"><a name="l01088"></a><span class="lineno"> 1088</span>&#160;  struct/class member name or parameter name has a wildcard XML tag name (i.e.</div><div class="line"><a name="l01089"></a><span class="lineno"> 1089</span>&#160;  matches any XML tag), or **b**) a type name that has a</div><div class="line"><a name="l01090"></a><span class="lineno"> 1090</span>&#160;  [document root element definition](#toxsd9-7).</div><div class="line"><a name="l01091"></a><span class="lineno"> 1091</span>&#160;</div><div class="line"><a name="l01092"></a><span class="lineno"> 1092</span>&#160;- Trailing underscores are removed (i.e. trailing underscores can be used to</div><div class="line"><a name="l01093"></a><span class="lineno"> 1093</span>&#160;  avoid name clashes with keywords).</div><div class="line"><a name="l01094"></a><span class="lineno"> 1094</span>&#160;</div><div class="line"><a name="l01095"></a><span class="lineno"> 1095</span>&#160;- Underscores within names are translated to hyphens (hyphens are more common</div><div class="line"><a name="l01096"></a><span class="lineno"> 1096</span>&#160;  in XML tag names).</div><div class="line"><a name="l01097"></a><span class="lineno"> 1097</span>&#160;</div><div class="line"><a name="l01098"></a><span class="lineno"> 1098</span>&#160;- `_USCORE` is translated to an underscore in the translated XML tag name.</div><div class="line"><a name="l01099"></a><span class="lineno"> 1099</span>&#160;</div><div class="line"><a name="l01100"></a><span class="lineno"> 1100</span>&#160;- `_DOT` is translated to a dot (&lt;i&gt;`.`&lt;/i&gt;) in the translated XML tag name.</div><div class="line"><a name="l01101"></a><span class="lineno"> 1101</span>&#160;</div><div class="line"><a name="l01102"></a><span class="lineno"> 1102</span>&#160;- `_xHHHH` is translated to the Unicode character with code point HHHH (hex).</div><div class="line"><a name="l01103"></a><span class="lineno"> 1103</span>&#160;</div><div class="line"><a name="l01104"></a><span class="lineno"> 1104</span>&#160;- C++11 Unicode identifier name characters in UTF-8 are translated as-is.</div><div class="line"><a name="l01105"></a><span class="lineno"> 1105</span>&#160;</div><div class="line"><a name="l01106"></a><span class="lineno"> 1106</span>&#160;For example, the C/C++ namespace qualified identifier name `s_a__my_way` is</div><div class="line"><a name="l01107"></a><span class="lineno"> 1107</span>&#160;translated to the XML tag name &lt;i&gt;`s-a:my-way`&lt;/i&gt; by translating the prefix `s_a`</div><div class="line"><a name="l01108"></a><span class="lineno"> 1108</span>&#160;and the local name `my_way`.</div><div class="line"><a name="l01109"></a><span class="lineno"> 1109</span>&#160;</div><div class="line"><a name="l01110"></a><span class="lineno"> 1110</span>&#160;Struct/class member and parameter name translation can be overruled by using</div><div class="line"><a name="l01111"></a><span class="lineno"> 1111</span>&#160;[backtick XML tags](#toxsd9-5-1) (with gSOAP 2.8.30 and greater).</div><div class="line"><a name="l01112"></a><span class="lineno"> 1112</span>&#160;</div><div class="line"><a name="l01113"></a><span class="lineno"> 1113</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l01114"></a><span class="lineno"> 1114</span>&#160;</div><div class="line"><a name="l01115"></a><span class="lineno"> 1115</span>&#160;C++ bool and C alternative                                             {#toxsd3}</div><div class="line"><a name="l01116"></a><span class="lineno"> 1116</span>&#160;-------------------------- </div><div class="line"><a name="l01117"></a><span class="lineno"> 1117</span>&#160;</div><div class="line"><a name="l01118"></a><span class="lineno"> 1118</span>&#160;The C++ `bool` type is bound to built-in XSD type &lt;i&gt;`xsd:boolean`&lt;/i&gt;.</div><div class="line"><a name="l01119"></a><span class="lineno"> 1119</span>&#160;</div><div class="line"><a name="l01120"></a><span class="lineno"> 1120</span>&#160;The C alternative is to define an enumeration:</div><div class="line"><a name="l01121"></a><span class="lineno"> 1121</span>&#160;</div><div class="line"><a name="l01122"></a><span class="lineno"> 1122</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01123"></a><span class="lineno"> 1123</span>&#160;    enum xsd__boolean { false_, true_ };</div><div class="line"><a name="l01124"></a><span class="lineno"> 1124</span>&#160;~~~</div><div class="line"><a name="l01125"></a><span class="lineno"> 1125</span>&#160;</div><div class="line"><a name="l01126"></a><span class="lineno"> 1126</span>&#160;or by defining an enumeration in C with pseudo-scoped enumeration constants:</div><div class="line"><a name="l01127"></a><span class="lineno"> 1127</span>&#160;</div><div class="line"><a name="l01128"></a><span class="lineno"> 1128</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01129"></a><span class="lineno"> 1129</span>&#160;    enum xsd__boolean { xsd__boolean__false, xsd__boolean__true };</div><div class="line"><a name="l01130"></a><span class="lineno"> 1130</span>&#160;~~~</div><div class="line"><a name="l01131"></a><span class="lineno"> 1131</span>&#160;</div><div class="line"><a name="l01132"></a><span class="lineno"> 1132</span>&#160;The XML value space of these types is &lt;i&gt;`false`&lt;/i&gt; and &lt;i&gt;`true`&lt;/i&gt;, but also accepted</div><div class="line"><a name="l01133"></a><span class="lineno"> 1133</span>&#160;are &lt;i&gt;`0`&lt;/i&gt; and &lt;i&gt;`1`&lt;/i&gt; values for &lt;i&gt;`false`&lt;/i&gt; and &lt;i&gt;`true`&lt;/i&gt;, respectively.</div><div class="line"><a name="l01134"></a><span class="lineno"> 1134</span>&#160;</div><div class="line"><a name="l01135"></a><span class="lineno"> 1135</span>&#160;To prevent name clashes, `false_` and `true_` have a trailing underscore in</div><div class="line"><a name="l01136"></a><span class="lineno"> 1136</span>&#160;their `enum` symbols.  Trailing underscores are removed from the XML value space.</div><div class="line"><a name="l01137"></a><span class="lineno"> 1137</span>&#160;</div><div class="line"><a name="l01138"></a><span class="lineno"> 1138</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l01139"></a><span class="lineno"> 1139</span>&#160;</div><div class="line"><a name="l01140"></a><span class="lineno"> 1140</span>&#160;Enumerations and bitmasks                                              {#toxsd4}</div><div class="line"><a name="l01141"></a><span class="lineno"> 1141</span>&#160;-------------------------</div><div class="line"><a name="l01142"></a><span class="lineno"> 1142</span>&#160;</div><div class="line"><a name="l01143"></a><span class="lineno"> 1143</span>&#160;Enumerations are mapped to XSD simpleType enumeration restrictions of</div><div class="line"><a name="l01144"></a><span class="lineno"> 1144</span>&#160;&lt;i&gt;`xsd:string`&lt;/i&gt;, &lt;i&gt;`xsd:QName`&lt;/i&gt;, and &lt;i&gt;`xsd:long`&lt;/i&gt;.</div><div class="line"><a name="l01145"></a><span class="lineno"> 1145</span>&#160;</div><div class="line"><a name="l01146"></a><span class="lineno"> 1146</span>&#160;Consider for example:</div><div class="line"><a name="l01147"></a><span class="lineno"> 1147</span>&#160;</div><div class="line"><a name="l01148"></a><span class="lineno"> 1148</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01149"></a><span class="lineno"> 1149</span>&#160;    enum ns__Color { RED, WHITE, BLUE };</div><div class="line"><a name="l01150"></a><span class="lineno"> 1150</span>&#160;~~~</div><div class="line"><a name="l01151"></a><span class="lineno"> 1151</span>&#160;</div><div class="line"><a name="l01152"></a><span class="lineno"> 1152</span>&#160;which maps to a simpleType restriction of &lt;i&gt;`xsd:string`&lt;/i&gt; in the soapcpp2-generated</div><div class="line"><a name="l01153"></a><span class="lineno"> 1153</span>&#160;schema:</div><div class="line"><a name="l01154"></a><span class="lineno"> 1154</span>&#160;</div><div class="line"><a name="l01155"></a><span class="lineno"> 1155</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l01156"></a><span class="lineno"> 1156</span>&#160;~~~{.xml}</div><div class="line"><a name="l01157"></a><span class="lineno"> 1157</span>&#160;    &lt;simpleType name=&quot;Color&quot;&gt;</div><div class="line"><a name="l01158"></a><span class="lineno"> 1158</span>&#160;      &lt;restriction base=&quot;xsd:string&quot;&gt;</div><div class="line"><a name="l01159"></a><span class="lineno"> 1159</span>&#160;        &lt;enumeration value=&quot;RED&quot;/&gt;</div><div class="line"><a name="l01160"></a><span class="lineno"> 1160</span>&#160;        &lt;enumeration value=&quot;WHITE&quot;/&gt;</div><div class="line"><a name="l01161"></a><span class="lineno"> 1161</span>&#160;        &lt;enumeration value=&quot;BLUE&quot;/&gt;</div><div class="line"><a name="l01162"></a><span class="lineno"> 1162</span>&#160;      &lt;/restriction&gt;</div><div class="line"><a name="l01163"></a><span class="lineno"> 1163</span>&#160;    &lt;/simpleType&gt;</div><div class="line"><a name="l01164"></a><span class="lineno"> 1164</span>&#160;~~~</div><div class="line"><a name="l01165"></a><span class="lineno"> 1165</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l01166"></a><span class="lineno"> 1166</span>&#160;</div><div class="line"><a name="l01167"></a><span class="lineno"> 1167</span>&#160;Enumeration name constants can be pseudo-scoped to prevent name clashes,</div><div class="line"><a name="l01168"></a><span class="lineno"> 1168</span>&#160;because enumeration name constants have a global scope in C and C++:</div><div class="line"><a name="l01169"></a><span class="lineno"> 1169</span>&#160;</div><div class="line"><a name="l01170"></a><span class="lineno"> 1170</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01171"></a><span class="lineno"> 1171</span>&#160;    enum ns__Color { ns__Color__RED, ns__Color__WHITE, ns__Color__BLUE };</div><div class="line"><a name="l01172"></a><span class="lineno"> 1172</span>&#160;~~~</div><div class="line"><a name="l01173"></a><span class="lineno"> 1173</span>&#160;</div><div class="line"><a name="l01174"></a><span class="lineno"> 1174</span>&#160;You can also use C++11 scoped enumerations to prevent name clashes:</div><div class="line"><a name="l01175"></a><span class="lineno"> 1175</span>&#160;</div><div class="line"><a name="l01176"></a><span class="lineno"> 1176</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01177"></a><span class="lineno"> 1177</span>&#160;    enum class ns__Color : int { RED, WHITE, BLUE };</div><div class="line"><a name="l01178"></a><span class="lineno"> 1178</span>&#160;~~~</div><div class="line"><a name="l01179"></a><span class="lineno"> 1179</span>&#160;</div><div class="line"><a name="l01180"></a><span class="lineno"> 1180</span>&#160;Here, the enumeration class base type `: int` is optional.  In place of `int`</div><div class="line"><a name="l01181"></a><span class="lineno"> 1181</span>&#160;in the example above, we can also use `int8_t`, `int16_t`, `int32_t`, or</div><div class="line"><a name="l01182"></a><span class="lineno"> 1182</span>&#160;`int64_t`.</div><div class="line"><a name="l01183"></a><span class="lineno"> 1183</span>&#160;</div><div class="line"><a name="l01184"></a><span class="lineno"> 1184</span>&#160;The XML value space of the enumertions defined above is &lt;i&gt;`RED`&lt;/i&gt;, &lt;i&gt;`WHITE`&lt;/i&gt;, and</div><div class="line"><a name="l01185"></a><span class="lineno"> 1185</span>&#160;&lt;i&gt;`BLUE`&lt;/i&gt;.</div><div class="line"><a name="l01186"></a><span class="lineno"> 1186</span>&#160;</div><div class="line"><a name="l01187"></a><span class="lineno"> 1187</span>&#160;Prefix-qualified enumeration name constants are mapped to simpleType</div><div class="line"><a name="l01188"></a><span class="lineno"> 1188</span>&#160;restrictions of &lt;i&gt;`xsd:QName`&lt;/i&gt;, for example:</div><div class="line"><a name="l01189"></a><span class="lineno"> 1189</span>&#160;</div><div class="line"><a name="l01190"></a><span class="lineno"> 1190</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01191"></a><span class="lineno"> 1191</span>&#160;    enum ns__types { xsd__int, xsd__float };</div><div class="line"><a name="l01192"></a><span class="lineno"> 1192</span>&#160;~~~</div><div class="line"><a name="l01193"></a><span class="lineno"> 1193</span>&#160;</div><div class="line"><a name="l01194"></a><span class="lineno"> 1194</span>&#160;which maps to a simpleType restriction of &lt;i&gt;`xsd:QName`&lt;/i&gt; in the soapcpp2-generated</div><div class="line"><a name="l01195"></a><span class="lineno"> 1195</span>&#160;schema:</div><div class="line"><a name="l01196"></a><span class="lineno"> 1196</span>&#160;</div><div class="line"><a name="l01197"></a><span class="lineno"> 1197</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l01198"></a><span class="lineno"> 1198</span>&#160;~~~{.xml}</div><div class="line"><a name="l01199"></a><span class="lineno"> 1199</span>&#160;    &lt;simpleType name=&quot;types&quot;&gt;</div><div class="line"><a name="l01200"></a><span class="lineno"> 1200</span>&#160;      &lt;restriction base=&quot;xsd:QName&quot;&gt;</div><div class="line"><a name="l01201"></a><span class="lineno"> 1201</span>&#160;        &lt;enumeration value=&quot;xsd:int&quot;/&gt;</div><div class="line"><a name="l01202"></a><span class="lineno"> 1202</span>&#160;        &lt;enumeration value=&quot;xsd:float&quot;/&gt;</div><div class="line"><a name="l01203"></a><span class="lineno"> 1203</span>&#160;      &lt;/restriction&gt;</div><div class="line"><a name="l01204"></a><span class="lineno"> 1204</span>&#160;    &lt;/simpleType&gt;</div><div class="line"><a name="l01205"></a><span class="lineno"> 1205</span>&#160;~~~</div><div class="line"><a name="l01206"></a><span class="lineno"> 1206</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l01207"></a><span class="lineno"> 1207</span>&#160;</div><div class="line"><a name="l01208"></a><span class="lineno"> 1208</span>&#160;Enumeration name constants can be pseudo-numeric as follows:</div><div class="line"><a name="l01209"></a><span class="lineno"> 1209</span>&#160;</div><div class="line"><a name="l01210"></a><span class="lineno"> 1210</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01211"></a><span class="lineno"> 1211</span>&#160;    enum ns__Primes { _3 = 3, _5 = 5, _7 = 7, _11 = 11 };</div><div class="line"><a name="l01212"></a><span class="lineno"> 1212</span>&#160;~~~</div><div class="line"><a name="l01213"></a><span class="lineno"> 1213</span>&#160;</div><div class="line"><a name="l01214"></a><span class="lineno"> 1214</span>&#160;which maps to a simpleType restriction of &lt;i&gt;`xsd:long`&lt;/i&gt;:</div><div class="line"><a name="l01215"></a><span class="lineno"> 1215</span>&#160;</div><div class="line"><a name="l01216"></a><span class="lineno"> 1216</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l01217"></a><span class="lineno"> 1217</span>&#160;~~~{.xml}</div><div class="line"><a name="l01218"></a><span class="lineno"> 1218</span>&#160;    &lt;simpleType name=&quot;Color&quot;&gt;</div><div class="line"><a name="l01219"></a><span class="lineno"> 1219</span>&#160;      &lt;restriction base=&quot;xsd:long&quot;&gt;</div><div class="line"><a name="l01220"></a><span class="lineno"> 1220</span>&#160;        &lt;enumeration value=&quot;3&quot;/&gt;</div><div class="line"><a name="l01221"></a><span class="lineno"> 1221</span>&#160;        &lt;enumeration value=&quot;5&quot;/&gt;</div><div class="line"><a name="l01222"></a><span class="lineno"> 1222</span>&#160;        &lt;enumeration value=&quot;7&quot;/&gt;</div><div class="line"><a name="l01223"></a><span class="lineno"> 1223</span>&#160;        &lt;enumeration value=&quot;11&quot;/&gt;</div><div class="line"><a name="l01224"></a><span class="lineno"> 1224</span>&#160;      &lt;/restriction&gt;</div><div class="line"><a name="l01225"></a><span class="lineno"> 1225</span>&#160;    &lt;/simpleType&gt;</div><div class="line"><a name="l01226"></a><span class="lineno"> 1226</span>&#160;~~~</div><div class="line"><a name="l01227"></a><span class="lineno"> 1227</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l01228"></a><span class="lineno"> 1228</span>&#160;</div><div class="line"><a name="l01229"></a><span class="lineno"> 1229</span>&#160;The XML value space of this type is &lt;i&gt;`3`&lt;/i&gt;, &lt;i&gt;`5`&lt;/i&gt;, &lt;i&gt;`7`&lt;/i&gt;, and &lt;i&gt;`11`&lt;/i&gt;.</div><div class="line"><a name="l01230"></a><span class="lineno"> 1230</span>&#160;</div><div class="line"><a name="l01231"></a><span class="lineno"> 1231</span>&#160;Besides (pseudo-) scoped enumerations, another way to prevent name clashes</div><div class="line"><a name="l01232"></a><span class="lineno"> 1232</span>&#160;accross enumerations is to start an enumeration name constant with one</div><div class="line"><a name="l01233"></a><span class="lineno"> 1233</span>&#160;underscore or followed it by any number of underscores, which makes it</div><div class="line"><a name="l01234"></a><span class="lineno"> 1234</span>&#160;unique.  The leading and trailing underscores are removed from the XML value</div><div class="line"><a name="l01235"></a><span class="lineno"> 1235</span>&#160;space.</div><div class="line"><a name="l01236"></a><span class="lineno"> 1236</span>&#160;</div><div class="line"><a name="l01237"></a><span class="lineno"> 1237</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01238"></a><span class="lineno"> 1238</span>&#160;    enum ns__ABC { A, B, C };</div><div class="line"><a name="l01239"></a><span class="lineno"> 1239</span>&#160;    enum ns__BA  { B, A };    // BAD: B = 1 but B is already defined as 2</div><div class="line"><a name="l01240"></a><span class="lineno"> 1240</span>&#160;    enum ns__BA_ { B_, A_ };  // OK</div><div class="line"><a name="l01241"></a><span class="lineno"> 1241</span>&#160;~~~</div><div class="line"><a name="l01242"></a><span class="lineno"> 1242</span>&#160;</div><div class="line"><a name="l01243"></a><span class="lineno"> 1243</span>&#160;The gSOAP soapcpp2 tool permits reusing enumeration name constants across</div><div class="line"><a name="l01244"></a><span class="lineno"> 1244</span>&#160;(non-scoped) enumerations as long as these values are assigned the same</div><div class="line"><a name="l01245"></a><span class="lineno"> 1245</span>&#160;constant.  Therefore, the following is permitted:</div><div class="line"><a name="l01246"></a><span class="lineno"> 1246</span>&#160;</div><div class="line"><a name="l01247"></a><span class="lineno"> 1247</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01248"></a><span class="lineno"> 1248</span>&#160;    enum ns__Primes { _3 = 3, _5 = 5, _7 = 7, _11 = 11 };</div><div class="line"><a name="l01249"></a><span class="lineno"> 1249</span>&#160;    enum ns__Throws { _1 = 1, _2 = 2, _3 = 3, _4 = 4, _5 = 5, _6 = 6 };</div><div class="line"><a name="l01250"></a><span class="lineno"> 1250</span>&#160;~~~</div><div class="line"><a name="l01251"></a><span class="lineno"> 1251</span>&#160;</div><div class="line"><a name="l01252"></a><span class="lineno"> 1252</span>&#160;A bitmask type is an `enum*` &quot;product enumeration&quot; with a geometric,</div><div class="line"><a name="l01253"></a><span class="lineno"> 1253</span>&#160;power-of-two sequence of values assigned to the enumeration constants:</div><div class="line"><a name="l01254"></a><span class="lineno"> 1254</span>&#160;</div><div class="line"><a name="l01255"></a><span class="lineno"> 1255</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01256"></a><span class="lineno"> 1256</span>&#160;    enum* ns__Options { SSL3, TLS10, TLS11, TLS12, TLS13 };</div><div class="line"><a name="l01257"></a><span class="lineno"> 1257</span>&#160;~~~</div><div class="line"><a name="l01258"></a><span class="lineno"> 1258</span>&#160;</div><div class="line"><a name="l01259"></a><span class="lineno"> 1259</span>&#160;where the product enum assigns 1 to `SSL3`, 2 to `TLS10`, 4 to `TLS11`, 8</div><div class="line"><a name="l01260"></a><span class="lineno"> 1260</span>&#160;to `TLS12`, and 16 to `TLS13`, which allows these enumeration constants to be</div><div class="line"><a name="l01261"></a><span class="lineno"> 1261</span>&#160;used in composing bitmasks with `|` (bitwise or) `&amp;` (bitwise and), and `~`</div><div class="line"><a name="l01262"></a><span class="lineno"> 1262</span>&#160;(bitwise not):</div><div class="line"><a name="l01263"></a><span class="lineno"> 1263</span>&#160;</div><div class="line"><a name="l01264"></a><span class="lineno"> 1264</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01265"></a><span class="lineno"> 1265</span>&#160;    enum ns__Options options = (enum ns__Options)(SSL3 | TLS10 | TLS11 | TLS12 | TLS13);</div><div class="line"><a name="l01266"></a><span class="lineno"> 1266</span>&#160;    if (options &amp; SSL3) // if SSL3 is an option, warn and remove from options</div><div class="line"><a name="l01267"></a><span class="lineno"> 1267</span>&#160;    {</div><div class="line"><a name="l01268"></a><span class="lineno"> 1268</span>&#160;      warning();</div><div class="line"><a name="l01269"></a><span class="lineno"> 1269</span>&#160;      options &amp;= ~SSL3;</div><div class="line"><a name="l01270"></a><span class="lineno"> 1270</span>&#160;    }</div><div class="line"><a name="l01271"></a><span class="lineno"> 1271</span>&#160;~~~</div><div class="line"><a name="l01272"></a><span class="lineno"> 1272</span>&#160;</div><div class="line"><a name="l01273"></a><span class="lineno"> 1273</span>&#160;The bitmask type maps to a simpleType list restriction of &lt;i&gt;`xsd:string`&lt;/i&gt; in the</div><div class="line"><a name="l01274"></a><span class="lineno"> 1274</span>&#160;soapcpp2-generated XML schema:</div><div class="line"><a name="l01275"></a><span class="lineno"> 1275</span>&#160;</div><div class="line"><a name="l01276"></a><span class="lineno"> 1276</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l01277"></a><span class="lineno"> 1277</span>&#160;~~~{.xml}</div><div class="line"><a name="l01278"></a><span class="lineno"> 1278</span>&#160;    &lt;simpleType name=&quot;Options&quot;&gt;</div><div class="line"><a name="l01279"></a><span class="lineno"> 1279</span>&#160;      &lt;list&gt;</div><div class="line"><a name="l01280"></a><span class="lineno"> 1280</span>&#160;        &lt;restriction base=&quot;xsd:string&quot;&gt;</div><div class="line"><a name="l01281"></a><span class="lineno"> 1281</span>&#160;          &lt;enumeration value=&quot;SSL3&quot;/&gt;</div><div class="line"><a name="l01282"></a><span class="lineno"> 1282</span>&#160;          &lt;enumeration value=&quot;TLS10&quot;/&gt;</div><div class="line"><a name="l01283"></a><span class="lineno"> 1283</span>&#160;          &lt;enumeration value=&quot;TLS11&quot;/&gt;</div><div class="line"><a name="l01284"></a><span class="lineno"> 1284</span>&#160;          &lt;enumeration value=&quot;TLS12&quot;/&gt;</div><div class="line"><a name="l01285"></a><span class="lineno"> 1285</span>&#160;          &lt;enumeration value=&quot;TLS13&quot;/&gt;</div><div class="line"><a name="l01286"></a><span class="lineno"> 1286</span>&#160;        &lt;/restriction&gt;</div><div class="line"><a name="l01287"></a><span class="lineno"> 1287</span>&#160;      &lt;/list&gt;</div><div class="line"><a name="l01288"></a><span class="lineno"> 1288</span>&#160;    &lt;/simpleType&gt;</div><div class="line"><a name="l01289"></a><span class="lineno"> 1289</span>&#160;~~~</div><div class="line"><a name="l01290"></a><span class="lineno"> 1290</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l01291"></a><span class="lineno"> 1291</span>&#160;</div><div class="line"><a name="l01292"></a><span class="lineno"> 1292</span>&#160;The XML value space of this type consists of all 16 possible subsets of the</div><div class="line"><a name="l01293"></a><span class="lineno"> 1293</span>&#160;four values, represented by an XML string with space-separated values.  For</div><div class="line"><a name="l01294"></a><span class="lineno"> 1294</span>&#160;example, the bitmask `TLS10 | TLS11 | TLS12` equals 14 and is represented by</div><div class="line"><a name="l01295"></a><span class="lineno"> 1295</span>&#160;the XML text &lt;i&gt;`TLS10 TLS11 TLS12`&lt;/i&gt;.</div><div class="line"><a name="l01296"></a><span class="lineno"> 1296</span>&#160;</div><div class="line"><a name="l01297"></a><span class="lineno"> 1297</span>&#160;You can also use C++11 scoped enumerations with bitmasks using `enum*` product</div><div class="line"><a name="l01298"></a><span class="lineno"> 1298</span>&#160;enumerations:</div><div class="line"><a name="l01299"></a><span class="lineno"> 1299</span>&#160;</div><div class="line"><a name="l01300"></a><span class="lineno"> 1300</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01301"></a><span class="lineno"> 1301</span>&#160;    enum* class ns__Options { SSL3, TLS10, TLS11, TLS12, TLS13 };</div><div class="line"><a name="l01302"></a><span class="lineno"> 1302</span>&#160;~~~</div><div class="line"><a name="l01303"></a><span class="lineno"> 1303</span>&#160;</div><div class="line"><a name="l01304"></a><span class="lineno"> 1304</span>&#160;The base type of a scoped enumeration bitmask, when explicitly given, is</div><div class="line"><a name="l01305"></a><span class="lineno"> 1305</span>&#160;ignored.  The base type is either `int` or `int64_t`, depending on the number</div><div class="line"><a name="l01306"></a><span class="lineno"> 1306</span>&#160;of constants enumerated in the bitmask.</div><div class="line"><a name="l01307"></a><span class="lineno"> 1307</span>&#160;</div><div class="line"><a name="l01308"></a><span class="lineno"> 1308</span>&#160;To convert `enum` name constants and bitmasks to a string, we use the</div><div class="line"><a name="l01309"></a><span class="lineno"> 1309</span>&#160;auto-generated function for enum `T`:</div><div class="line"><a name="l01310"></a><span class="lineno"> 1310</span>&#160;</div><div class="line"><a name="l01311"></a><span class="lineno"> 1311</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01312"></a><span class="lineno"> 1312</span>&#160;    const char *soap_T2s(struct soap*, enum T val)</div><div class="line"><a name="l01313"></a><span class="lineno"> 1313</span>&#160;~~~</div><div class="line"><a name="l01314"></a><span class="lineno"> 1314</span>&#160;</div><div class="line"><a name="l01315"></a><span class="lineno"> 1315</span>&#160;The string returned is stored in an internal buffer of the current `soap`</div><div class="line"><a name="l01316"></a><span class="lineno"> 1316</span>&#160;context, so you should copy it to keep it from being overwritten.  For example,</div><div class="line"><a name="l01317"></a><span class="lineno"> 1317</span>&#160;use `char *soap_strdup(struct soap*, const char*)`.</div><div class="line"><a name="l01318"></a><span class="lineno"> 1318</span>&#160;</div><div class="line"><a name="l01319"></a><span class="lineno"> 1319</span>&#160;To convert a string to an `enum` constant or bitmask, we use the auto-generated</div><div class="line"><a name="l01320"></a><span class="lineno"> 1320</span>&#160;function</div><div class="line"><a name="l01321"></a><span class="lineno"> 1321</span>&#160;</div><div class="line"><a name="l01322"></a><span class="lineno"> 1322</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01323"></a><span class="lineno"> 1323</span>&#160;    int soap_s2T(struct soap*, const char *str, enum T *val)</div><div class="line"><a name="l01324"></a><span class="lineno"> 1324</span>&#160;~~~</div><div class="line"><a name="l01325"></a><span class="lineno"> 1325</span>&#160;  </div><div class="line"><a name="l01326"></a><span class="lineno"> 1326</span>&#160;This function takes the name (or names, space-separated for bitmasks) of</div><div class="line"><a name="l01327"></a><span class="lineno"> 1327</span>&#160;the enumeration constant in a string `str`.  Names should be given without the</div><div class="line"><a name="l01328"></a><span class="lineno"> 1328</span>&#160;pseudo-scope prefix and without trailing underscores.  The function sets `val`</div><div class="line"><a name="l01329"></a><span class="lineno"> 1329</span>&#160;to the corresponding integer enum constant or to a bitmask.  The function</div><div class="line"><a name="l01330"></a><span class="lineno"> 1330</span>&#160;returns `SOAP_OK` (zero) on success or an error if the string is not a valid</div><div class="line"><a name="l01331"></a><span class="lineno"> 1331</span>&#160;enumeration name.</div><div class="line"><a name="l01332"></a><span class="lineno"> 1332</span>&#160;</div><div class="line"><a name="l01333"></a><span class="lineno"> 1333</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l01334"></a><span class="lineno"> 1334</span>&#160;</div><div class="line"><a name="l01335"></a><span class="lineno"> 1335</span>&#160;Numerical types                                                        {#toxsd5}</div><div class="line"><a name="l01336"></a><span class="lineno"> 1336</span>&#160;---------------</div><div class="line"><a name="l01337"></a><span class="lineno"> 1337</span>&#160;</div><div class="line"><a name="l01338"></a><span class="lineno"> 1338</span>&#160;Integer and floating point types are mapped to the equivalent built-in XSD</div><div class="line"><a name="l01339"></a><span class="lineno"> 1339</span>&#160;types with the same sign and bit width.</div><div class="line"><a name="l01340"></a><span class="lineno"> 1340</span>&#160;</div><div class="line"><a name="l01341"></a><span class="lineno"> 1341</span>&#160;The `size_t` type is transient (not serializable) because its width is platform</div><div class="line"><a name="l01342"></a><span class="lineno"> 1342</span>&#160;dependent.  We recommend to use `uint64_t` instead.</div><div class="line"><a name="l01343"></a><span class="lineno"> 1343</span>&#160;</div><div class="line"><a name="l01344"></a><span class="lineno"> 1344</span>&#160;The XML value space of integer types are their decimal representations without</div><div class="line"><a name="l01345"></a><span class="lineno"> 1345</span>&#160;loss of precision.</div><div class="line"><a name="l01346"></a><span class="lineno"> 1346</span>&#160;</div><div class="line"><a name="l01347"></a><span class="lineno"> 1347</span>&#160;The XML value space of floating point types are their decimal representations.</div><div class="line"><a name="l01348"></a><span class="lineno"> 1348</span>&#160;The decimal representations are formatted with the printf format string `&quot;%.9G&quot;`</div><div class="line"><a name="l01349"></a><span class="lineno"> 1349</span>&#160;for floats and the printf format string `&quot;%.17lG&quot;` for double.  To change the</div><div class="line"><a name="l01350"></a><span class="lineno"> 1350</span>&#160;format strings, we can assign new strings to the following `soap` context</div><div class="line"><a name="l01351"></a><span class="lineno"> 1351</span>&#160;members:</div><div class="line"><a name="l01352"></a><span class="lineno"> 1352</span>&#160;</div><div class="line"><a name="l01353"></a><span class="lineno"> 1353</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01354"></a><span class="lineno"> 1354</span>&#160;    soap.float_format       = &quot;%g&quot;;</div><div class="line"><a name="l01355"></a><span class="lineno"> 1355</span>&#160;    soap.double_format      = &quot;%lg&quot;;</div><div class="line"><a name="l01356"></a><span class="lineno"> 1356</span>&#160;    soap.long_double_format = &quot;%Lg&quot;;</div><div class="line"><a name="l01357"></a><span class="lineno"> 1357</span>&#160;~~~</div><div class="line"><a name="l01358"></a><span class="lineno"> 1358</span>&#160;</div><div class="line"><a name="l01359"></a><span class="lineno"> 1359</span>&#160;Decimal representations may result in a loss of precision of the least</div><div class="line"><a name="l01360"></a><span class="lineno"> 1360</span>&#160;significant decimal.  Therefore, the format strings that are used by default</div><div class="line"><a name="l01361"></a><span class="lineno"> 1361</span>&#160;are sufficiently precise to avoid loss, but this may result in long decimal</div><div class="line"><a name="l01362"></a><span class="lineno"> 1362</span>&#160;fractions in the XML value space.</div><div class="line"><a name="l01363"></a><span class="lineno"> 1363</span>&#160;</div><div class="line"><a name="l01364"></a><span class="lineno"> 1364</span>&#160;The `long double` extended floating point type requires a custom serializer:</div><div class="line"><a name="l01365"></a><span class="lineno"> 1365</span>&#160;</div><div class="line"><a name="l01366"></a><span class="lineno"> 1366</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01367"></a><span class="lineno"> 1367</span>&#160;    #import &quot;custom/long_double.h&quot;</div><div class="line"><a name="l01368"></a><span class="lineno"> 1368</span>&#160;    ... // use long double</div><div class="line"><a name="l01369"></a><span class="lineno"> 1369</span>&#160;~~~</div><div class="line"><a name="l01370"></a><span class="lineno"> 1370</span>&#160;</div><div class="line"><a name="l01371"></a><span class="lineno"> 1371</span>&#160;You can now use `long double`, which has a serializer that serializes this type</div><div class="line"><a name="l01372"></a><span class="lineno"> 1372</span>&#160;as &lt;i&gt;`xsd:decimal`&lt;/i&gt;.  Compile and link your code with the file</div><div class="line"><a name="l01373"></a><span class="lineno"> 1373</span>&#160;&lt;i&gt;`gsoap/custom/long_double.c`&lt;/i&gt;.</div><div class="line"><a name="l01374"></a><span class="lineno"> 1374</span>&#160;</div><div class="line"><a name="l01375"></a><span class="lineno"> 1375</span>&#160;The value space of floating point values includes the special values</div><div class="line"><a name="l01376"></a><span class="lineno"> 1376</span>&#160;&lt;i&gt;`INF`&lt;/i&gt;, &lt;i&gt;`-INF`&lt;/i&gt;, and &lt;i&gt;`NaN`&lt;/i&gt;.  You can check a value for plus</div><div class="line"><a name="l01377"></a><span class="lineno"> 1377</span>&#160;or minus infinity and not-a-number as follows:</div><div class="line"><a name="l01378"></a><span class="lineno"> 1378</span>&#160;</div><div class="line"><a name="l01379"></a><span class="lineno"> 1379</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01380"></a><span class="lineno"> 1380</span>&#160;    soap_isinf(x) &amp;&amp; x &gt; 0 // is x INF?</div><div class="line"><a name="l01381"></a><span class="lineno"> 1381</span>&#160;    soap_isinf(x) &amp;&amp; x &lt; 0 // is x -INF?</div><div class="line"><a name="l01382"></a><span class="lineno"> 1382</span>&#160;    soap_isnan(x)          // is x NaN?</div><div class="line"><a name="l01383"></a><span class="lineno"> 1383</span>&#160;~~~</div><div class="line"><a name="l01384"></a><span class="lineno"> 1384</span>&#160;</div><div class="line"><a name="l01385"></a><span class="lineno"> 1385</span>&#160;To assign these values, use:</div><div class="line"><a name="l01386"></a><span class="lineno"> 1386</span>&#160;</div><div class="line"><a name="l01387"></a><span class="lineno"> 1387</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01388"></a><span class="lineno"> 1388</span>&#160;    // x is float       // x is double, long double, or __float128</div><div class="line"><a name="l01389"></a><span class="lineno"> 1389</span>&#160;    x = FLT_PINFY;      x = DBL_PINFTY;</div><div class="line"><a name="l01390"></a><span class="lineno"> 1390</span>&#160;    x = FLT_NINFY;      x = DBL_NINFTY;</div><div class="line"><a name="l01391"></a><span class="lineno"> 1391</span>&#160;    x = FLT_NAN;        x = DBL_NAN;</div><div class="line"><a name="l01392"></a><span class="lineno"> 1392</span>&#160;~~~</div><div class="line"><a name="l01393"></a><span class="lineno"> 1393</span>&#160;</div><div class="line"><a name="l01394"></a><span class="lineno"> 1394</span>&#160;If your system supports `__float128` then you can also use this 128 bit</div><div class="line"><a name="l01395"></a><span class="lineno"> 1395</span>&#160;floating point type with a custom serializer:</div><div class="line"><a name="l01396"></a><span class="lineno"> 1396</span>&#160;</div><div class="line"><a name="l01397"></a><span class="lineno"> 1397</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01398"></a><span class="lineno"> 1398</span>&#160;    #import &quot;custom/float128.h&quot;</div><div class="line"><a name="l01399"></a><span class="lineno"> 1399</span>&#160;    ... // use xsd__decimal</div><div class="line"><a name="l01400"></a><span class="lineno"> 1400</span>&#160;~~~</div><div class="line"><a name="l01401"></a><span class="lineno"> 1401</span>&#160;</div><div class="line"><a name="l01402"></a><span class="lineno"> 1402</span>&#160;Then use the `xsd__decimal` alias of `__float128`, which has a serializer.  Do</div><div class="line"><a name="l01403"></a><span class="lineno"> 1403</span>&#160;not use `__float128` directly, which is transient (not serializable).</div><div class="line"><a name="l01404"></a><span class="lineno"> 1404</span>&#160;</div><div class="line"><a name="l01405"></a><span class="lineno"> 1405</span>&#160;To check for &lt;i&gt;`INF`&lt;/i&gt;, &lt;i&gt;`-INF`&lt;/i&gt;, and &lt;i&gt;`NaN`&lt;/i&gt; of a `__float128`</div><div class="line"><a name="l01406"></a><span class="lineno"> 1406</span>&#160;value use:</div><div class="line"><a name="l01407"></a><span class="lineno"> 1407</span>&#160;</div><div class="line"><a name="l01408"></a><span class="lineno"> 1408</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01409"></a><span class="lineno"> 1409</span>&#160;    isinfq(x) &amp;&amp; x &gt; 0 // is x INF?</div><div class="line"><a name="l01410"></a><span class="lineno"> 1410</span>&#160;    isinfq(x) &amp;&amp; x &lt; 0 // is x -INF?</div><div class="line"><a name="l01411"></a><span class="lineno"> 1411</span>&#160;    isnanq(x)          // is x NaN?</div><div class="line"><a name="l01412"></a><span class="lineno"> 1412</span>&#160;~~~</div><div class="line"><a name="l01413"></a><span class="lineno"> 1413</span>&#160;</div><div class="line"><a name="l01414"></a><span class="lineno"> 1414</span>&#160;The range of a `typedef`-defined numerical type can be restricted using the range</div><div class="line"><a name="l01415"></a><span class="lineno"> 1415</span>&#160;`:` operator with inclusive lower and upper bounds.  For example:</div><div class="line"><a name="l01416"></a><span class="lineno"> 1416</span>&#160;</div><div class="line"><a name="l01417"></a><span class="lineno"> 1417</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01418"></a><span class="lineno"> 1418</span>&#160;    typedef int ns__narrow -10 : 10;</div><div class="line"><a name="l01419"></a><span class="lineno"> 1419</span>&#160;~~~</div><div class="line"><a name="l01420"></a><span class="lineno"> 1420</span>&#160;</div><div class="line"><a name="l01421"></a><span class="lineno"> 1421</span>&#160;This maps to a simpleType restriction of &lt;i&gt;`xsd:int`&lt;/i&gt; in the soapcpp2-generated</div><div class="line"><a name="l01422"></a><span class="lineno"> 1422</span>&#160;schema:</div><div class="line"><a name="l01423"></a><span class="lineno"> 1423</span>&#160;</div><div class="line"><a name="l01424"></a><span class="lineno"> 1424</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l01425"></a><span class="lineno"> 1425</span>&#160;~~~{.xml}</div><div class="line"><a name="l01426"></a><span class="lineno"> 1426</span>&#160;    &lt;simpleType name=&quot;narrow&quot;&gt;</div><div class="line"><a name="l01427"></a><span class="lineno"> 1427</span>&#160;      &lt;restriction base=&quot;xsd:int&quot;&gt;</div><div class="line"><a name="l01428"></a><span class="lineno"> 1428</span>&#160;        &lt;minInclusive value=&quot;-10&quot;/&gt;</div><div class="line"><a name="l01429"></a><span class="lineno"> 1429</span>&#160;        &lt;maxInclusive value=&quot;10&quot;/&gt;</div><div class="line"><a name="l01430"></a><span class="lineno"> 1430</span>&#160;      &lt;/restriction&gt;</div><div class="line"><a name="l01431"></a><span class="lineno"> 1431</span>&#160;    &lt;/simpleType&gt;</div><div class="line"><a name="l01432"></a><span class="lineno"> 1432</span>&#160;~~~</div><div class="line"><a name="l01433"></a><span class="lineno"> 1433</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l01434"></a><span class="lineno"> 1434</span>&#160;</div><div class="line"><a name="l01435"></a><span class="lineno"> 1435</span>&#160;The lower and upper bound of a range are optional.  When omitted, values are</div><div class="line"><a name="l01436"></a><span class="lineno"> 1436</span>&#160;not bound from below or from above, respectively.</div><div class="line"><a name="l01437"></a><span class="lineno"> 1437</span>&#160;</div><div class="line"><a name="l01438"></a><span class="lineno"> 1438</span>&#160;The range of a floating point `typedef`-defined type can be restricted within</div><div class="line"><a name="l01439"></a><span class="lineno"> 1439</span>&#160;floating point constant bounds.</div><div class="line"><a name="l01440"></a><span class="lineno"> 1440</span>&#160;</div><div class="line"><a name="l01441"></a><span class="lineno"> 1441</span>&#160;Also with a floating point `typedef` a `printf`-format pattern can be given of the</div><div class="line"><a name="l01442"></a><span class="lineno"> 1442</span>&#160;form `&quot;%[width][.precision]f&quot;` to format decimal values using the given width</div><div class="line"><a name="l01443"></a><span class="lineno"> 1443</span>&#160;and precision fields:</div><div class="line"><a name="l01444"></a><span class="lineno"> 1444</span>&#160;</div><div class="line"><a name="l01445"></a><span class="lineno"> 1445</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01446"></a><span class="lineno"> 1446</span>&#160;    typedef float ns__PH &quot;%5.2f&quot; 0.0 : 14.0;</div><div class="line"><a name="l01447"></a><span class="lineno"> 1447</span>&#160;~~~</div><div class="line"><a name="l01448"></a><span class="lineno"> 1448</span>&#160;</div><div class="line"><a name="l01449"></a><span class="lineno"> 1449</span>&#160;This maps to a simpleType restriction of &lt;i&gt;`xsd:float`&lt;/i&gt; in the soapcpp2-generated</div><div class="line"><a name="l01450"></a><span class="lineno"> 1450</span>&#160;schema:</div><div class="line"><a name="l01451"></a><span class="lineno"> 1451</span>&#160;</div><div class="line"><a name="l01452"></a><span class="lineno"> 1452</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l01453"></a><span class="lineno"> 1453</span>&#160;~~~{.xml}</div><div class="line"><a name="l01454"></a><span class="lineno"> 1454</span>&#160;    &lt;simpleType name=&quot;PH&quot;&gt;</div><div class="line"><a name="l01455"></a><span class="lineno"> 1455</span>&#160;      &lt;restriction base=&quot;xsd:float&quot;&gt;</div><div class="line"><a name="l01456"></a><span class="lineno"> 1456</span>&#160;        &lt;totalDigits value=&quot;5&quot;/&gt;</div><div class="line"><a name="l01457"></a><span class="lineno"> 1457</span>&#160;        &lt;fractionDigits value=&quot;2&quot;/&gt;</div><div class="line"><a name="l01458"></a><span class="lineno"> 1458</span>&#160;        &lt;minInclusive value=&quot;0&quot;/&gt;</div><div class="line"><a name="l01459"></a><span class="lineno"> 1459</span>&#160;        &lt;maxInclusive value=&quot;14&quot;/&gt;</div><div class="line"><a name="l01460"></a><span class="lineno"> 1460</span>&#160;      &lt;/restriction&gt;</div><div class="line"><a name="l01461"></a><span class="lineno"> 1461</span>&#160;    &lt;/simpleType&gt;</div><div class="line"><a name="l01462"></a><span class="lineno"> 1462</span>&#160;~~~</div><div class="line"><a name="l01463"></a><span class="lineno"> 1463</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l01464"></a><span class="lineno"> 1464</span>&#160;</div><div class="line"><a name="l01465"></a><span class="lineno"> 1465</span>&#160;For exclusive bounds, we use the `&lt;` operator instead of the `:` range</div><div class="line"><a name="l01466"></a><span class="lineno"> 1466</span>&#160;operator:</div><div class="line"><a name="l01467"></a><span class="lineno"> 1467</span>&#160;</div><div class="line"><a name="l01468"></a><span class="lineno"> 1468</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01469"></a><span class="lineno"> 1469</span>&#160;    typedef float ns__epsilon 0.0 &lt; 1.0;</div><div class="line"><a name="l01470"></a><span class="lineno"> 1470</span>&#160;~~~</div><div class="line"><a name="l01471"></a><span class="lineno"> 1471</span>&#160;</div><div class="line"><a name="l01472"></a><span class="lineno"> 1472</span>&#160;Values `eps` of `ns__epsilon` are restricted between `0.0 &lt; eps &lt; 1.0`.</div><div class="line"><a name="l01473"></a><span class="lineno"> 1473</span>&#160;</div><div class="line"><a name="l01474"></a><span class="lineno"> 1474</span>&#160;This maps to a simpleType restriction of &lt;i&gt;`xsd:float`&lt;/i&gt; in the soapcpp2-generated</div><div class="line"><a name="l01475"></a><span class="lineno"> 1475</span>&#160;schema:</div><div class="line"><a name="l01476"></a><span class="lineno"> 1476</span>&#160;</div><div class="line"><a name="l01477"></a><span class="lineno"> 1477</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l01478"></a><span class="lineno"> 1478</span>&#160;~~~{.xml}</div><div class="line"><a name="l01479"></a><span class="lineno"> 1479</span>&#160;    &lt;simpleType name=&quot;epsilon&quot;&gt;</div><div class="line"><a name="l01480"></a><span class="lineno"> 1480</span>&#160;      &lt;restriction base=&quot;xsd:float&quot;&gt;</div><div class="line"><a name="l01481"></a><span class="lineno"> 1481</span>&#160;        &lt;minExclusive value=&quot;0&quot;/&gt;</div><div class="line"><a name="l01482"></a><span class="lineno"> 1482</span>&#160;        &lt;maxExclusive value=&quot;1&quot;/&gt;</div><div class="line"><a name="l01483"></a><span class="lineno"> 1483</span>&#160;      &lt;/restriction&gt;</div><div class="line"><a name="l01484"></a><span class="lineno"> 1484</span>&#160;    &lt;/simpleType&gt;</div><div class="line"><a name="l01485"></a><span class="lineno"> 1485</span>&#160;~~~</div><div class="line"><a name="l01486"></a><span class="lineno"> 1486</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l01487"></a><span class="lineno"> 1487</span>&#160;</div><div class="line"><a name="l01488"></a><span class="lineno"> 1488</span>&#160;To make just one of the bounds exclusive, while keeping the other bound</div><div class="line"><a name="l01489"></a><span class="lineno"> 1489</span>&#160;inclusive, we add a `&lt;` on the left or on the right side of the range &#39;:&#39;</div><div class="line"><a name="l01490"></a><span class="lineno"> 1490</span>&#160;operator.  For example:</div><div class="line"><a name="l01491"></a><span class="lineno"> 1491</span>&#160;</div><div class="line"><a name="l01492"></a><span class="lineno"> 1492</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01493"></a><span class="lineno"> 1493</span>&#160;    typedef float ns__pos 0.0 &lt; : ; // 0.0 &lt; pos</div><div class="line"><a name="l01494"></a><span class="lineno"> 1494</span>&#160;    typedef float ns__neg : &lt; 0.0 ; // neg &lt; 0.0</div><div class="line"><a name="l01495"></a><span class="lineno"> 1495</span>&#160;~~~</div><div class="line"><a name="l01496"></a><span class="lineno"> 1496</span>&#160;</div><div class="line"><a name="l01497"></a><span class="lineno"> 1497</span>&#160;It is valid to make both left and right side exclusive with `&lt; : &lt;` which is in</div><div class="line"><a name="l01498"></a><span class="lineno"> 1498</span>&#160;fact identical to the exlusive range `&lt;` operator:</div><div class="line"><a name="l01499"></a><span class="lineno"> 1499</span>&#160;</div><div class="line"><a name="l01500"></a><span class="lineno"> 1500</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01501"></a><span class="lineno"> 1501</span>&#160;    typedef float ns__epsilon 0.0 &lt; : &lt; 1.0; // 0.0 &lt; eps &lt; 1.0</div><div class="line"><a name="l01502"></a><span class="lineno"> 1502</span>&#160;~~~</div><div class="line"><a name="l01503"></a><span class="lineno"> 1503</span>&#160;</div><div class="line"><a name="l01504"></a><span class="lineno"> 1504</span>&#160;It helps to think of the `:` as a placeholder of the value between the two</div><div class="line"><a name="l01505"></a><span class="lineno"> 1505</span>&#160;bounds, which is easier to memorize than the shorthand forms of bounds from</div><div class="line"><a name="l01506"></a><span class="lineno"> 1506</span>&#160;which the `:` is removed:</div><div class="line"><a name="l01507"></a><span class="lineno"> 1507</span>&#160;</div><div class="line"><a name="l01508"></a><span class="lineno"> 1508</span>&#160;| bounds       | validation check | shorthand   |</div><div class="line"><a name="l01509"></a><span class="lineno"> 1509</span>&#160;| ------------ | ---------------- | ----------- |</div><div class="line"><a name="l01510"></a><span class="lineno"> 1510</span>&#160;| `1 :       ` | 1 &lt;= x           | `1        ` |</div><div class="line"><a name="l01511"></a><span class="lineno"> 1511</span>&#160;| `1 : 10    ` | 1 &lt;= x &lt;= 10     |             |</div><div class="line"><a name="l01512"></a><span class="lineno"> 1512</span>&#160;| `  : 10    ` |      x &lt;= 10     |             |</div><div class="line"><a name="l01513"></a><span class="lineno"> 1513</span>&#160;| `1 &lt; : &lt; 10` | 1 &lt;  x &lt;  10     | `1 &lt; 10   ` |</div><div class="line"><a name="l01514"></a><span class="lineno"> 1514</span>&#160;| `1   : &lt; 10` | 1 &lt;= x &lt;  10     |             |</div><div class="line"><a name="l01515"></a><span class="lineno"> 1515</span>&#160;| `    : &lt; 10` |      x &lt;  10     | `  &lt; 10   ` |</div><div class="line"><a name="l01516"></a><span class="lineno"> 1516</span>&#160;| `1 &lt; :     ` | 1 &lt;  x           | `1 &lt;      ` |</div><div class="line"><a name="l01517"></a><span class="lineno"> 1517</span>&#160;| `1 &lt; : 10  ` | 1 &lt;  x &lt;= 10     |             |</div><div class="line"><a name="l01518"></a><span class="lineno"> 1518</span>&#160;</div><div class="line"><a name="l01519"></a><span class="lineno"> 1519</span>&#160;Besides `float`, also `double` and `long double` values can be restricted.  For</div><div class="line"><a name="l01520"></a><span class="lineno"> 1520</span>&#160;example, consider a nonzero probability extended floating point precision type:</div><div class="line"><a name="l01521"></a><span class="lineno"> 1521</span>&#160;</div><div class="line"><a name="l01522"></a><span class="lineno"> 1522</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01523"></a><span class="lineno"> 1523</span>&#160;    #import &quot;custom/long_double.h&quot;</div><div class="line"><a name="l01524"></a><span class="lineno"> 1524</span>&#160;    typedef long double ns__probability &quot;%16Lg&quot; 0.0 &lt; : 1.0;</div><div class="line"><a name="l01525"></a><span class="lineno"> 1525</span>&#160;~~~</div><div class="line"><a name="l01526"></a><span class="lineno"> 1526</span>&#160;</div><div class="line"><a name="l01527"></a><span class="lineno"> 1527</span>&#160;Value range restrictions are validated by the parser for all inbound XML data.</div><div class="line"><a name="l01528"></a><span class="lineno"> 1528</span>&#160;A type fault `SOAP_TYPE` will be thrown by the deserializer if the value is out</div><div class="line"><a name="l01529"></a><span class="lineno"> 1529</span>&#160;of range.</div><div class="line"><a name="l01530"></a><span class="lineno"> 1530</span>&#160;</div><div class="line"><a name="l01531"></a><span class="lineno"> 1531</span>&#160;Finally, if your system supports `__int128_t` then you can also use this 128</div><div class="line"><a name="l01532"></a><span class="lineno"> 1532</span>&#160;bit integer type with a custom serializer:</div><div class="line"><a name="l01533"></a><span class="lineno"> 1533</span>&#160;</div><div class="line"><a name="l01534"></a><span class="lineno"> 1534</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01535"></a><span class="lineno"> 1535</span>&#160;    #import &quot;custom/int128.h&quot;</div><div class="line"><a name="l01536"></a><span class="lineno"> 1536</span>&#160;    ... // use xsd__integer</div><div class="line"><a name="l01537"></a><span class="lineno"> 1537</span>&#160;~~~</div><div class="line"><a name="l01538"></a><span class="lineno"> 1538</span>&#160;</div><div class="line"><a name="l01539"></a><span class="lineno"> 1539</span>&#160;Use the `xsd__integer` alias of `__int128_t`, which has a serializer.  Do not</div><div class="line"><a name="l01540"></a><span class="lineno"> 1540</span>&#160;use `__int128_t` directly, which is transient (not serializable).</div><div class="line"><a name="l01541"></a><span class="lineno"> 1541</span>&#160;</div><div class="line"><a name="l01542"></a><span class="lineno"> 1542</span>&#160;To convert numeric values to a string, we use the auto-generated function for</div><div class="line"><a name="l01543"></a><span class="lineno"> 1543</span>&#160;numeric type `T`:</div><div class="line"><a name="l01544"></a><span class="lineno"> 1544</span>&#160;</div><div class="line"><a name="l01545"></a><span class="lineno"> 1545</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01546"></a><span class="lineno"> 1546</span>&#160;    const char *soap_T2s(struct soap*, T val)</div><div class="line"><a name="l01547"></a><span class="lineno"> 1547</span>&#160;~~~</div><div class="line"><a name="l01548"></a><span class="lineno"> 1548</span>&#160;</div><div class="line"><a name="l01549"></a><span class="lineno"> 1549</span>&#160;For numeric types `T`, the string returned is stored in an internal buffer of</div><div class="line"><a name="l01550"></a><span class="lineno"> 1550</span>&#160;the current `soap` context, so you should copy it to keep it from being</div><div class="line"><a name="l01551"></a><span class="lineno"> 1551</span>&#160;overwritten.  For example, use `char *soap_strdup(struct soap*, const char*)`.</div><div class="line"><a name="l01552"></a><span class="lineno"> 1552</span>&#160;</div><div class="line"><a name="l01553"></a><span class="lineno"> 1553</span>&#160;To convert a string to a numeric value, we use the auto-generated function</div><div class="line"><a name="l01554"></a><span class="lineno"> 1554</span>&#160;</div><div class="line"><a name="l01555"></a><span class="lineno"> 1555</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01556"></a><span class="lineno"> 1556</span>&#160;    int soap_s2T(struct soap*, const char *str, T *val)</div><div class="line"><a name="l01557"></a><span class="lineno"> 1557</span>&#160;~~~</div><div class="line"><a name="l01558"></a><span class="lineno"> 1558</span>&#160;  </div><div class="line"><a name="l01559"></a><span class="lineno"> 1559</span>&#160;where `T` is for example `int`, `LONG64`, `float`, `decimal` (the custom</div><div class="line"><a name="l01560"></a><span class="lineno"> 1560</span>&#160;serializer name of `long double`) or `xsd__integer` (the custom serializer name</div><div class="line"><a name="l01561"></a><span class="lineno"> 1561</span>&#160;of `__int128_t`).  The function `soap_s2T` returns `SOAP_OK` on success or an</div><div class="line"><a name="l01562"></a><span class="lineno"> 1562</span>&#160;error when the value is not numeric.  For floating point types, `&quot;INF&quot;`, `&quot;-INF&quot;`</div><div class="line"><a name="l01563"></a><span class="lineno"> 1563</span>&#160;and `&quot;NaN&quot;` are valid strings to convert to numbers.</div><div class="line"><a name="l01564"></a><span class="lineno"> 1564</span>&#160;</div><div class="line"><a name="l01565"></a><span class="lineno"> 1565</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l01566"></a><span class="lineno"> 1566</span>&#160;</div><div class="line"><a name="l01567"></a><span class="lineno"> 1567</span>&#160;String types                                                           {#toxsd6}</div><div class="line"><a name="l01568"></a><span class="lineno"> 1568</span>&#160;------------</div><div class="line"><a name="l01569"></a><span class="lineno"> 1569</span>&#160;</div><div class="line"><a name="l01570"></a><span class="lineno"> 1570</span>&#160;String types are mapped to the built-in &lt;i&gt;`xsd:string`&lt;/i&gt; and &lt;i&gt;`xsd:QName`&lt;/i&gt; XSD types.</div><div class="line"><a name="l01571"></a><span class="lineno"> 1571</span>&#160;</div><div class="line"><a name="l01572"></a><span class="lineno"> 1572</span>&#160;The wide strings `wchar_t*` and `std::wstring` may contain Unicode that is</div><div class="line"><a name="l01573"></a><span class="lineno"> 1573</span>&#160;preserved in the XML value space.</div><div class="line"><a name="l01574"></a><span class="lineno"> 1574</span>&#160;</div><div class="line"><a name="l01575"></a><span class="lineno"> 1575</span>&#160;Strings `char*` and `std::string` can only contain extended Latin, but we can</div><div class="line"><a name="l01576"></a><span class="lineno"> 1576</span>&#160;store UTF-8 content that is preserved in the XML value space when the `soap`</div><div class="line"><a name="l01577"></a><span class="lineno"> 1577</span>&#160;context is initialized with the flag `SOAP_C_UTFSTRING`.</div><div class="line"><a name="l01578"></a><span class="lineno"> 1578</span>&#160;</div><div class="line"><a name="l01579"></a><span class="lineno"> 1579</span>&#160;@warning Beware that many XML 1.0 parsers reject all control characters (those</div><div class="line"><a name="l01580"></a><span class="lineno"> 1580</span>&#160;between `#x1` and `#x1F`) except for `#x9`, `#xA`, and `#xD`.  With the</div><div class="line"><a name="l01581"></a><span class="lineno"> 1581</span>&#160;newer XML 1.1 version parsers (including gSOAP) you should be fine.</div><div class="line"><a name="l01582"></a><span class="lineno"> 1582</span>&#160;</div><div class="line"><a name="l01583"></a><span class="lineno"> 1583</span>&#160;The length of a string of a `typedef`-defined string type can be restricted:</div><div class="line"><a name="l01584"></a><span class="lineno"> 1584</span>&#160;</div><div class="line"><a name="l01585"></a><span class="lineno"> 1585</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01586"></a><span class="lineno"> 1586</span>&#160;    typedef std::string ns__password 6 : 16;</div><div class="line"><a name="l01587"></a><span class="lineno"> 1587</span>&#160;~~~</div><div class="line"><a name="l01588"></a><span class="lineno"> 1588</span>&#160;</div><div class="line"><a name="l01589"></a><span class="lineno"> 1589</span>&#160;which maps to a simpleType restriction of &lt;i&gt;`xsd:string`&lt;/i&gt; in the soapcpp2-generated</div><div class="line"><a name="l01590"></a><span class="lineno"> 1590</span>&#160;schema:</div><div class="line"><a name="l01591"></a><span class="lineno"> 1591</span>&#160;</div><div class="line"><a name="l01592"></a><span class="lineno"> 1592</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l01593"></a><span class="lineno"> 1593</span>&#160;~~~{.xml}</div><div class="line"><a name="l01594"></a><span class="lineno"> 1594</span>&#160;    &lt;simpleType name=&quot;password&quot;&gt;</div><div class="line"><a name="l01595"></a><span class="lineno"> 1595</span>&#160;      &lt;restriction base=&quot;xsd:string&quot;&gt;</div><div class="line"><a name="l01596"></a><span class="lineno"> 1596</span>&#160;        &lt;minLength value=&quot;6&quot;/&gt;</div><div class="line"><a name="l01597"></a><span class="lineno"> 1597</span>&#160;        &lt;maxLength value=&quot;16&quot;/&gt;</div><div class="line"><a name="l01598"></a><span class="lineno"> 1598</span>&#160;      &lt;/restriction&gt;</div><div class="line"><a name="l01599"></a><span class="lineno"> 1599</span>&#160;    &lt;/simpleType&gt;</div><div class="line"><a name="l01600"></a><span class="lineno"> 1600</span>&#160;~~~</div><div class="line"><a name="l01601"></a><span class="lineno"> 1601</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l01602"></a><span class="lineno"> 1602</span>&#160;</div><div class="line"><a name="l01603"></a><span class="lineno"> 1603</span>&#160;String length restrictions are validated by the parser for inbound XML data.</div><div class="line"><a name="l01604"></a><span class="lineno"> 1604</span>&#160;A value length fault `SOAP_LENGTH` will be thrown by the deserializer if the</div><div class="line"><a name="l01605"></a><span class="lineno"> 1605</span>&#160;string is too long or too short.</div><div class="line"><a name="l01606"></a><span class="lineno"> 1606</span>&#160;</div><div class="line"><a name="l01607"></a><span class="lineno"> 1607</span>&#160;In addition, an XSD regex pattern restriction can be associated with a string</div><div class="line"><a name="l01608"></a><span class="lineno"> 1608</span>&#160;typedef:</div><div class="line"><a name="l01609"></a><span class="lineno"> 1609</span>&#160;</div><div class="line"><a name="l01610"></a><span class="lineno"> 1610</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01611"></a><span class="lineno"> 1611</span>&#160;    typedef std::string ns__password &quot;([a-zA-Z]|[0-9]|-)+&quot; 6 : 16;</div><div class="line"><a name="l01612"></a><span class="lineno"> 1612</span>&#160;~~~</div><div class="line"><a name="l01613"></a><span class="lineno"> 1613</span>&#160;</div><div class="line"><a name="l01614"></a><span class="lineno"> 1614</span>&#160;which maps to a simpleType restriction of &lt;i&gt;`xsd:string`&lt;/i&gt; in the soapcpp2-generated</div><div class="line"><a name="l01615"></a><span class="lineno"> 1615</span>&#160;schema:</div><div class="line"><a name="l01616"></a><span class="lineno"> 1616</span>&#160;</div><div class="line"><a name="l01617"></a><span class="lineno"> 1617</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l01618"></a><span class="lineno"> 1618</span>&#160;~~~{.xml}</div><div class="line"><a name="l01619"></a><span class="lineno"> 1619</span>&#160;    &lt;simpleType name=&quot;password&quot;&gt;</div><div class="line"><a name="l01620"></a><span class="lineno"> 1620</span>&#160;      &lt;restriction base=&quot;xsd:string&quot;&gt;</div><div class="line"><a name="l01621"></a><span class="lineno"> 1621</span>&#160;        &lt;pattern value=&quot;([a-zA-Z0-9]|-)+&quot;/&gt;</div><div class="line"><a name="l01622"></a><span class="lineno"> 1622</span>&#160;        &lt;minLength value=&quot;6&quot;/&gt;</div><div class="line"><a name="l01623"></a><span class="lineno"> 1623</span>&#160;        &lt;maxLength value=&quot;16&quot;/&gt;</div><div class="line"><a name="l01624"></a><span class="lineno"> 1624</span>&#160;      &lt;/restriction&gt;</div><div class="line"><a name="l01625"></a><span class="lineno"> 1625</span>&#160;    &lt;/simpleType&gt;</div><div class="line"><a name="l01626"></a><span class="lineno"> 1626</span>&#160;~~~</div><div class="line"><a name="l01627"></a><span class="lineno"> 1627</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l01628"></a><span class="lineno"> 1628</span>&#160;</div><div class="line"><a name="l01629"></a><span class="lineno"> 1629</span>&#160;Pattern restrictions are validated by the parser for inbound XML data only if</div><div class="line"><a name="l01630"></a><span class="lineno"> 1630</span>&#160;the `soap::fsvalidate` and `soap::fwvalidate` callbacks are defined.</div><div class="line"><a name="l01631"></a><span class="lineno"> 1631</span>&#160;</div><div class="line"><a name="l01632"></a><span class="lineno"> 1632</span>&#160;Exclusive length bounds can be used with strings:</div><div class="line"><a name="l01633"></a><span class="lineno"> 1633</span>&#160;</div><div class="line"><a name="l01634"></a><span class="lineno"> 1634</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01635"></a><span class="lineno"> 1635</span>&#160;    typedef std::string ns__string255 : &lt; 256; // same as 0 : 255</div><div class="line"><a name="l01636"></a><span class="lineno"> 1636</span>&#160;~~~</div><div class="line"><a name="l01637"></a><span class="lineno"> 1637</span>&#160;</div><div class="line"><a name="l01638"></a><span class="lineno"> 1638</span>&#160;Fixed-size strings (`char[N]`) are rare occurrences in the wild, but apparently</div><div class="line"><a name="l01639"></a><span class="lineno"> 1639</span>&#160;still used in some projects to store strings.  To facilitate fixed-size string</div><div class="line"><a name="l01640"></a><span class="lineno"> 1640</span>&#160;serialization, use &lt;b&gt;`soapcpp2 -b`&lt;/b&gt; option &lt;b&gt;`-b`&lt;/b&gt;.  For example:</div><div class="line"><a name="l01641"></a><span class="lineno"> 1641</span>&#160;</div><div class="line"><a name="l01642"></a><span class="lineno"> 1642</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01643"></a><span class="lineno"> 1643</span>&#160;    typedef char ns__buffer[10]; // requires soapcpp2 option -b</div><div class="line"><a name="l01644"></a><span class="lineno"> 1644</span>&#160;~~~</div><div class="line"><a name="l01645"></a><span class="lineno"> 1645</span>&#160;</div><div class="line"><a name="l01646"></a><span class="lineno"> 1646</span>&#160;which maps to a simpleType restriction of &lt;i&gt;`xsd:string`&lt;/i&gt; in the soapcpp2-generated</div><div class="line"><a name="l01647"></a><span class="lineno"> 1647</span>&#160;schema:</div><div class="line"><a name="l01648"></a><span class="lineno"> 1648</span>&#160;</div><div class="line"><a name="l01649"></a><span class="lineno"> 1649</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l01650"></a><span class="lineno"> 1650</span>&#160;~~~{.xml}</div><div class="line"><a name="l01651"></a><span class="lineno"> 1651</span>&#160;    &lt;simpleType name=&quot;buffer&quot;&gt;</div><div class="line"><a name="l01652"></a><span class="lineno"> 1652</span>&#160;      &lt;restriction base=&quot;xsd:string&quot;&gt;</div><div class="line"><a name="l01653"></a><span class="lineno"> 1653</span>&#160;        &lt;maxLength value=&quot;9&quot;/&gt;</div><div class="line"><a name="l01654"></a><span class="lineno"> 1654</span>&#160;      &lt;/restriction&gt;</div><div class="line"><a name="l01655"></a><span class="lineno"> 1655</span>&#160;    &lt;/simpleType&gt;</div><div class="line"><a name="l01656"></a><span class="lineno"> 1656</span>&#160;~~~</div><div class="line"><a name="l01657"></a><span class="lineno"> 1657</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l01658"></a><span class="lineno"> 1658</span>&#160;</div><div class="line"><a name="l01659"></a><span class="lineno"> 1659</span>&#160;Fixed-size strings must contain NUL-terminated text and should not contain raw</div><div class="line"><a name="l01660"></a><span class="lineno"> 1660</span>&#160;binary data.  Also, the length limitation is more restrictive for UTF-8 content</div><div class="line"><a name="l01661"></a><span class="lineno"> 1661</span>&#160;(enabled with the `SOAP_C_UTFSTRING`) that requires multibyte character</div><div class="line"><a name="l01662"></a><span class="lineno"> 1662</span>&#160;encodings.  As a consequence, UTF-8 content may be truncated to fit.</div><div class="line"><a name="l01663"></a><span class="lineno"> 1663</span>&#160;</div><div class="line"><a name="l01664"></a><span class="lineno"> 1664</span>&#160;Raw binary data can be stored in a `xsd__base64Binary` or `xsd__hexBinary`</div><div class="line"><a name="l01665"></a><span class="lineno"> 1665</span>&#160;structure, or transmitted as a MIME attachment.</div><div class="line"><a name="l01666"></a><span class="lineno"> 1666</span>&#160;</div><div class="line"><a name="l01667"></a><span class="lineno"> 1667</span>&#160;The built-in `_QName` type is a regular C string type (`char*`) that maps to</div><div class="line"><a name="l01668"></a><span class="lineno"> 1668</span>&#160;&lt;i&gt;`xsd:QName`&lt;/i&gt; but has the added advantage that it holds normalized qualified names.</div><div class="line"><a name="l01669"></a><span class="lineno"> 1669</span>&#160;There are actually two forms of normalized QName content, to ensure any QName</div><div class="line"><a name="l01670"></a><span class="lineno"> 1670</span>&#160;is represented accurately:</div><div class="line"><a name="l01671"></a><span class="lineno"> 1671</span>&#160;</div><div class="line"><a name="l01672"></a><span class="lineno"> 1672</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01673"></a><span class="lineno"> 1673</span>&#160;    &quot;prefix:name&quot;</div><div class="line"><a name="l01674"></a><span class="lineno"> 1674</span>&#160;    &quot;\&quot;URI\&quot;:name&quot;</div><div class="line"><a name="l01675"></a><span class="lineno"> 1675</span>&#160;~~~</div><div class="line"><a name="l01676"></a><span class="lineno"> 1676</span>&#160;</div><div class="line"><a name="l01677"></a><span class="lineno"> 1677</span>&#160;The first form of string is used when the prefix (and the binding URI) is</div><div class="line"><a name="l01678"></a><span class="lineno"> 1678</span>&#160;defined in the namespace table and is bound to a URI (see the .nsmap file).</div><div class="line"><a name="l01679"></a><span class="lineno"> 1679</span>&#160;The second form is used when the URI is not defined in the namespace table and</div><div class="line"><a name="l01680"></a><span class="lineno"> 1680</span>&#160;therefore no prefix is available to bind and normalize the URI to.</div><div class="line"><a name="l01681"></a><span class="lineno"> 1681</span>&#160;</div><div class="line"><a name="l01682"></a><span class="lineno"> 1682</span>&#160;A `_QName` string may contain a sequence of space-separated QName values, not</div><div class="line"><a name="l01683"></a><span class="lineno"> 1683</span>&#160;just one, and all QName values are normalized to the format shown above.</div><div class="line"><a name="l01684"></a><span class="lineno"> 1684</span>&#160;</div><div class="line"><a name="l01685"></a><span class="lineno"> 1685</span>&#160;To define a `std::string` base type for &lt;i&gt;`xsd:QName`&lt;/i&gt;, we use a `typedef`:</div><div class="line"><a name="l01686"></a><span class="lineno"> 1686</span>&#160;</div><div class="line"><a name="l01687"></a><span class="lineno"> 1687</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01688"></a><span class="lineno"> 1688</span>&#160;    typedef std::string xsd__QName;</div><div class="line"><a name="l01689"></a><span class="lineno"> 1689</span>&#160;~~~</div><div class="line"><a name="l01690"></a><span class="lineno"> 1690</span>&#160;</div><div class="line"><a name="l01691"></a><span class="lineno"> 1691</span>&#160;The `xsd__QName` string content is normalized, just as with the `_QName`</div><div class="line"><a name="l01692"></a><span class="lineno"> 1692</span>&#160;normalization.</div><div class="line"><a name="l01693"></a><span class="lineno"> 1693</span>&#160;</div><div class="line"><a name="l01694"></a><span class="lineno"> 1694</span>&#160;To serialize strings that contain literal XML content to be reproduced in the</div><div class="line"><a name="l01695"></a><span class="lineno"> 1695</span>&#160;XML value space, use the built-in `_XML` string type, which is a regular C</div><div class="line"><a name="l01696"></a><span class="lineno"> 1696</span>&#160;string type (`char*`) that maps to plain XML CDATA.</div><div class="line"><a name="l01697"></a><span class="lineno"> 1697</span>&#160;</div><div class="line"><a name="l01698"></a><span class="lineno"> 1698</span>&#160;To define a `std::string` base type for literal XML content, use a `typedef`:</div><div class="line"><a name="l01699"></a><span class="lineno"> 1699</span>&#160;</div><div class="line"><a name="l01700"></a><span class="lineno"> 1700</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01701"></a><span class="lineno"> 1701</span>&#160;    typedef std::string XML;</div><div class="line"><a name="l01702"></a><span class="lineno"> 1702</span>&#160;~~~</div><div class="line"><a name="l01703"></a><span class="lineno"> 1703</span>&#160;</div><div class="line"><a name="l01704"></a><span class="lineno"> 1704</span>&#160;Strings can hold any of the values of the XSD built-in primitive types.  We can</div><div class="line"><a name="l01705"></a><span class="lineno"> 1705</span>&#160;use a string `typedef` to declare the use of the string type as a XSD built-in</div><div class="line"><a name="l01706"></a><span class="lineno"> 1706</span>&#160;type:</div><div class="line"><a name="l01707"></a><span class="lineno"> 1707</span>&#160;</div><div class="line"><a name="l01708"></a><span class="lineno"> 1708</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01709"></a><span class="lineno"> 1709</span>&#160;    typedef std::string xsd__token;</div><div class="line"><a name="l01710"></a><span class="lineno"> 1710</span>&#160;~~~</div><div class="line"><a name="l01711"></a><span class="lineno"> 1711</span>&#160;</div><div class="line"><a name="l01712"></a><span class="lineno"> 1712</span>&#160;You must ensure that the string values we populate in this type conform to the</div><div class="line"><a name="l01713"></a><span class="lineno"> 1713</span>&#160;XML standard, which in case of &lt;i&gt;`xsd:token`&lt;/i&gt; is the lexical and value spaces of</div><div class="line"><a name="l01714"></a><span class="lineno"> 1714</span>&#160;&lt;i&gt;`xsd:token`&lt;/i&gt; are the sets of all strings after whitespace replacement of any</div><div class="line"><a name="l01715"></a><span class="lineno"> 1715</span>&#160;occurrence of `#x9`, `#xA` , and `#xD` by `#x20` and collapsing.</div><div class="line"><a name="l01716"></a><span class="lineno"> 1716</span>&#160;</div><div class="line"><a name="l01717"></a><span class="lineno"> 1717</span>&#160;As of version 2.8.49, the gSOAP parser will automatically collapse or replace</div><div class="line"><a name="l01718"></a><span class="lineno"> 1718</span>&#160;the white space content when receiving data for XSD types that require white</div><div class="line"><a name="l01719"></a><span class="lineno"> 1719</span>&#160;space collapsed or replaced.  This normalization is applied to strings</div><div class="line"><a name="l01720"></a><span class="lineno"> 1720</span>&#160;directly.  The decision to collapse or replace is based on the `typedef` name</div><div class="line"><a name="l01721"></a><span class="lineno"> 1721</span>&#160;corresponding to the built-in string-based XSD type.</div><div class="line"><a name="l01722"></a><span class="lineno"> 1722</span>&#160;</div><div class="line"><a name="l01723"></a><span class="lineno"> 1723</span>&#160;To copy `char*` or `wchar_t*` strings with a context that manages the allocated</div><div class="line"><a name="l01724"></a><span class="lineno"> 1724</span>&#160;memory, use functions</div><div class="line"><a name="l01725"></a><span class="lineno"> 1725</span>&#160;</div><div class="line"><a name="l01726"></a><span class="lineno"> 1726</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01727"></a><span class="lineno"> 1727</span>&#160;    char *soap_strdup(struct soap*, const char*)</div><div class="line"><a name="l01728"></a><span class="lineno"> 1728</span>&#160;    wchar_t *soap_wstrdup(struct soap*, const wchar_t*)</div><div class="line"><a name="l01729"></a><span class="lineno"> 1729</span>&#160;~~~</div><div class="line"><a name="l01730"></a><span class="lineno"> 1730</span>&#160;</div><div class="line"><a name="l01731"></a><span class="lineno"> 1731</span>&#160;To convert a wide string to a UTF-8 encoded string, use function</div><div class="line"><a name="l01732"></a><span class="lineno"> 1732</span>&#160;</div><div class="line"><a name="l01733"></a><span class="lineno"> 1733</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01734"></a><span class="lineno"> 1734</span>&#160;    const char* SOAP_FMAC2 soap_wchar2s(struct soap*, const wchar_t *s)</div><div class="line"><a name="l01735"></a><span class="lineno"> 1735</span>&#160;~~~</div><div class="line"><a name="l01736"></a><span class="lineno"> 1736</span>&#160;</div><div class="line"><a name="l01737"></a><span class="lineno"> 1737</span>&#160;The function allocates and returns a string, with its memory being managed by</div><div class="line"><a name="l01738"></a><span class="lineno"> 1738</span>&#160;the context.</div><div class="line"><a name="l01739"></a><span class="lineno"> 1739</span>&#160;</div><div class="line"><a name="l01740"></a><span class="lineno"> 1740</span>&#160;To convert a UTF-8 encoded string to a wide string, use function</div><div class="line"><a name="l01741"></a><span class="lineno"> 1741</span>&#160;</div><div class="line"><a name="l01742"></a><span class="lineno"> 1742</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01743"></a><span class="lineno"> 1743</span>&#160;    int soap_s2wchar(struct soap*, const char *from, wchar_t **to, long minlen, long maxlen)</div><div class="line"><a name="l01744"></a><span class="lineno"> 1744</span>&#160;~~~</div><div class="line"><a name="l01745"></a><span class="lineno"> 1745</span>&#160;</div><div class="line"><a name="l01746"></a><span class="lineno"> 1746</span>&#160;where `to` is set to point to an allocated `wchar_t*` string.  Pass `-1` for</div><div class="line"><a name="l01747"></a><span class="lineno"> 1747</span>&#160;`minlen` and `maxlen` to ignore length constraints on the target string.  The</div><div class="line"><a name="l01748"></a><span class="lineno"> 1748</span>&#160;function returns `SOAP_OK` or an error when the length constraints are not met.</div><div class="line"><a name="l01749"></a><span class="lineno"> 1749</span>&#160;</div><div class="line"><a name="l01750"></a><span class="lineno"> 1750</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l01751"></a><span class="lineno"> 1751</span>&#160;</div><div class="line"><a name="l01752"></a><span class="lineno"> 1752</span>&#160;Date and time types                                                    {#toxsd7}</div><div class="line"><a name="l01753"></a><span class="lineno"> 1753</span>&#160;-------------------</div><div class="line"><a name="l01754"></a><span class="lineno"> 1754</span>&#160;</div><div class="line"><a name="l01755"></a><span class="lineno"> 1755</span>&#160;The C/C++ `time_t` type is mapped to the built-in &lt;i&gt;`xsd:dateTime`&lt;/i&gt; XSD type that</div><div class="line"><a name="l01756"></a><span class="lineno"> 1756</span>&#160;represents a date and time within a time zone (typically UTC).</div><div class="line"><a name="l01757"></a><span class="lineno"> 1757</span>&#160;</div><div class="line"><a name="l01758"></a><span class="lineno"> 1758</span>&#160;The XML value space contains ISO 8601 Gregorian time instances of the form</div><div class="line"><a name="l01759"></a><span class="lineno"> 1759</span>&#160;&lt;i&gt;`[-]CCYY-MM-DDThh:mm:ss.sss[Z|(+|-)hh:mm]`&lt;/i&gt;, where &lt;i&gt;`Z`&lt;/i&gt; is the UTC time zone</div><div class="line"><a name="l01760"></a><span class="lineno"> 1760</span>&#160;or a time zone offset &lt;i&gt;`(+|-)hh:mm]`&lt;/i&gt; from UTC is used.</div><div class="line"><a name="l01761"></a><span class="lineno"> 1761</span>&#160;</div><div class="line"><a name="l01762"></a><span class="lineno"> 1762</span>&#160;A `time_t` value is considered and represented in UTC by the serializer.</div><div class="line"><a name="l01763"></a><span class="lineno"> 1763</span>&#160;</div><div class="line"><a name="l01764"></a><span class="lineno"> 1764</span>&#160;Because the `time_t` value range is restricted to dates after 01/01/1970 and</div><div class="line"><a name="l01765"></a><span class="lineno"> 1765</span>&#160;before 2038 assuming `time_t` is a `long` 32 bit, care must be taken to ensure</div><div class="line"><a name="l01766"></a><span class="lineno"> 1766</span>&#160;the range of &lt;i&gt;`xsd:dateTime`&lt;/i&gt; values in XML exchanges do not exceed the `time_t`</div><div class="line"><a name="l01767"></a><span class="lineno"> 1767</span>&#160;range.</div><div class="line"><a name="l01768"></a><span class="lineno"> 1768</span>&#160;</div><div class="line"><a name="l01769"></a><span class="lineno"> 1769</span>&#160;This restriction does not hold for `struct tm` (&lt;i&gt;`time.h`&lt;/i&gt; library), which we can use</div><div class="line"><a name="l01770"></a><span class="lineno"> 1770</span>&#160;to store and exchange a date and time in UTC without date range restrictions.</div><div class="line"><a name="l01771"></a><span class="lineno"> 1771</span>&#160;The serializer uses the `struct tm` members directly for the XML value space of</div><div class="line"><a name="l01772"></a><span class="lineno"> 1772</span>&#160;&lt;i&gt;`xsd:dateTime`&lt;/i&gt;:</div><div class="line"><a name="l01773"></a><span class="lineno"> 1773</span>&#160;</div><div class="line"><a name="l01774"></a><span class="lineno"> 1774</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01775"></a><span class="lineno"> 1775</span>&#160;    struct tm</div><div class="line"><a name="l01776"></a><span class="lineno"> 1776</span>&#160;    {</div><div class="line"><a name="l01777"></a><span class="lineno"> 1777</span>&#160;        int    tm_sec;   // seconds (0 - 60)</div><div class="line"><a name="l01778"></a><span class="lineno"> 1778</span>&#160;        int    tm_min;   // minutes (0 - 59)</div><div class="line"><a name="l01779"></a><span class="lineno"> 1779</span>&#160;        int    tm_hour;  // hours (0 - 23)</div><div class="line"><a name="l01780"></a><span class="lineno"> 1780</span>&#160;        int    tm_mday;  // day of month (1 - 31)</div><div class="line"><a name="l01781"></a><span class="lineno"> 1781</span>&#160;        int    tm_mon;   // month of year (0 - 11)</div><div class="line"><a name="l01782"></a><span class="lineno"> 1782</span>&#160;        int    tm_year;  // year - 1900</div><div class="line"><a name="l01783"></a><span class="lineno"> 1783</span>&#160;        int    tm_wday;  // day of week (Sunday = 0) (NOT USED)</div><div class="line"><a name="l01784"></a><span class="lineno"> 1784</span>&#160;        int    tm_yday;  // day of year (0 - 365) (NOT USED)</div><div class="line"><a name="l01785"></a><span class="lineno"> 1785</span>&#160;        int    tm_isdst; // is summer time in effect?</div><div class="line"><a name="l01786"></a><span class="lineno"> 1786</span>&#160;        char*  tm_zone;  // abbreviation of timezone (NOT USED)</div><div class="line"><a name="l01787"></a><span class="lineno"> 1787</span>&#160;    };</div><div class="line"><a name="l01788"></a><span class="lineno"> 1788</span>&#160;~~~</div><div class="line"><a name="l01789"></a><span class="lineno"> 1789</span>&#160;</div><div class="line"><a name="l01790"></a><span class="lineno"> 1790</span>&#160;You will lose the day of the week information.  It is always Sunday</div><div class="line"><a name="l01791"></a><span class="lineno"> 1791</span>&#160;(`tm_wday=0`) and the day of the year is not set either.  The time zone is UTC.</div><div class="line"><a name="l01792"></a><span class="lineno"> 1792</span>&#160;</div><div class="line"><a name="l01793"></a><span class="lineno"> 1793</span>&#160;This `struct tm` type is mapped to the built-in &lt;i&gt;`xsd:dateTime`&lt;/i&gt; XSD type and</div><div class="line"><a name="l01794"></a><span class="lineno"> 1794</span>&#160;serialized with the custom serializer &lt;i&gt;`gsoap/custom/struct_tm.h`&lt;/i&gt; that declares a</div><div class="line"><a name="l01795"></a><span class="lineno"> 1795</span>&#160;`xsd__dateTime` type:</div><div class="line"><a name="l01796"></a><span class="lineno"> 1796</span>&#160;</div><div class="line"><a name="l01797"></a><span class="lineno"> 1797</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01798"></a><span class="lineno"> 1798</span>&#160;    #import &quot;custom/struct_tm.h&quot; // import typedef struct tm xsd__dateTime;</div><div class="line"><a name="l01799"></a><span class="lineno"> 1799</span>&#160;    ... // use xsd__dateTime</div><div class="line"><a name="l01800"></a><span class="lineno"> 1800</span>&#160;~~~</div><div class="line"><a name="l01801"></a><span class="lineno"> 1801</span>&#160;</div><div class="line"><a name="l01802"></a><span class="lineno"> 1802</span>&#160;Compile and link your code with &lt;i&gt;`gsoap/custom/struct_tm.c`&lt;/i&gt;.</div><div class="line"><a name="l01803"></a><span class="lineno"> 1803</span>&#160;</div><div class="line"><a name="l01804"></a><span class="lineno"> 1804</span>&#160;The `struct timeval` (&lt;i&gt;`sys/time.h`&lt;/i&gt; library) type is mapped to the</div><div class="line"><a name="l01805"></a><span class="lineno"> 1805</span>&#160;built-in &lt;i&gt;`xsd:dateTime`&lt;/i&gt; XSD type and serialized with the custom serializer</div><div class="line"><a name="l01806"></a><span class="lineno"> 1806</span>&#160;&lt;i&gt;`gsoap/custom/struct_timeval.h`&lt;/i&gt; that declares a `xsd__dateTime` type:</div><div class="line"><a name="l01807"></a><span class="lineno"> 1807</span>&#160;</div><div class="line"><a name="l01808"></a><span class="lineno"> 1808</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01809"></a><span class="lineno"> 1809</span>&#160;    #import &quot;custom/struct_timeval.h&quot; // import typedef struct timeval xsd__dateTime;</div><div class="line"><a name="l01810"></a><span class="lineno"> 1810</span>&#160;    ... // use xsd__dateTime</div><div class="line"><a name="l01811"></a><span class="lineno"> 1811</span>&#160;~~~</div><div class="line"><a name="l01812"></a><span class="lineno"> 1812</span>&#160;</div><div class="line"><a name="l01813"></a><span class="lineno"> 1813</span>&#160;Compile and link your code with &lt;i&gt;`gsoap/custom/struct_timeval.c`&lt;/i&gt;.</div><div class="line"><a name="l01814"></a><span class="lineno"> 1814</span>&#160;</div><div class="line"><a name="l01815"></a><span class="lineno"> 1815</span>&#160;The same value range restrictions apply to `struct timeval` as they apply to</div><div class="line"><a name="l01816"></a><span class="lineno"> 1816</span>&#160;`time_t`.  The added benefit of `struct timeval` is the addition of a</div><div class="line"><a name="l01817"></a><span class="lineno"> 1817</span>&#160;microsecond-precise clock:</div><div class="line"><a name="l01818"></a><span class="lineno"> 1818</span>&#160;</div><div class="line"><a name="l01819"></a><span class="lineno"> 1819</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01820"></a><span class="lineno"> 1820</span>&#160;    struct timeval</div><div class="line"><a name="l01821"></a><span class="lineno"> 1821</span>&#160;    {</div><div class="line"><a name="l01822"></a><span class="lineno"> 1822</span>&#160;        time_t       tv_sec;  // seconds since Jan. 1, 1970</div><div class="line"><a name="l01823"></a><span class="lineno"> 1823</span>&#160;        suseconds_t  tv_usec; // and microseconds</div><div class="line"><a name="l01824"></a><span class="lineno"> 1824</span>&#160;    };</div><div class="line"><a name="l01825"></a><span class="lineno"> 1825</span>&#160;~~~</div><div class="line"><a name="l01826"></a><span class="lineno"> 1826</span>&#160;</div><div class="line"><a name="l01827"></a><span class="lineno"> 1827</span>&#160;A C++11 `std::chrono::system_clock::time_point` type is mapped to the built-in</div><div class="line"><a name="l01828"></a><span class="lineno"> 1828</span>&#160;&lt;i&gt;`xsd:dateTime`&lt;/i&gt; XSD type and serialized with the custom serializer</div><div class="line"><a name="l01829"></a><span class="lineno"> 1829</span>&#160;&lt;i&gt;`gsoap/custom/chrono_time_point.h`&lt;/i&gt; that declares a `xsd__dateTime` type:</div><div class="line"><a name="l01830"></a><span class="lineno"> 1830</span>&#160;</div><div class="line"><a name="l01831"></a><span class="lineno"> 1831</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01832"></a><span class="lineno"> 1832</span>&#160;    #import &quot;custom/chrono_time_point.h&quot; // import typedef std::chrono::system_clock::time_point xsd__dateTime;</div><div class="line"><a name="l01833"></a><span class="lineno"> 1833</span>&#160;    ... // use xsd__dateTime</div><div class="line"><a name="l01834"></a><span class="lineno"> 1834</span>&#160;~~~</div><div class="line"><a name="l01835"></a><span class="lineno"> 1835</span>&#160;</div><div class="line"><a name="l01836"></a><span class="lineno"> 1836</span>&#160;Compile and link your code with &lt;i&gt;`gsoap/custom/chrono_time_point.cpp`&lt;/i&gt;.</div><div class="line"><a name="l01837"></a><span class="lineno"> 1837</span>&#160;</div><div class="line"><a name="l01838"></a><span class="lineno"> 1838</span>&#160;The `struct tm` type is mapped to the built-in &lt;i&gt;`xsd:date`&lt;/i&gt; XSD type and serialized</div><div class="line"><a name="l01839"></a><span class="lineno"> 1839</span>&#160;with the custom serializer &lt;i&gt;`gsoap/custom/struct_tm_date.h`&lt;/i&gt; that declares a</div><div class="line"><a name="l01840"></a><span class="lineno"> 1840</span>&#160;`xsd__date` type:</div><div class="line"><a name="l01841"></a><span class="lineno"> 1841</span>&#160;</div><div class="line"><a name="l01842"></a><span class="lineno"> 1842</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01843"></a><span class="lineno"> 1843</span>&#160;    #import &quot;custom/struct_tm_date.h&quot; // import typedef struct tm xsd__date;</div><div class="line"><a name="l01844"></a><span class="lineno"> 1844</span>&#160;    ... // use xsd__date</div><div class="line"><a name="l01845"></a><span class="lineno"> 1845</span>&#160;~~~</div><div class="line"><a name="l01846"></a><span class="lineno"> 1846</span>&#160;</div><div class="line"><a name="l01847"></a><span class="lineno"> 1847</span>&#160;Compile and link your code with &lt;i&gt;`gsoap/custom/struct_tm_date.c`&lt;/i&gt;.</div><div class="line"><a name="l01848"></a><span class="lineno"> 1848</span>&#160;</div><div class="line"><a name="l01849"></a><span class="lineno"> 1849</span>&#160;The XML value space of &lt;i&gt;`xsd:date`&lt;/i&gt; are Gregorian calendar dates of the form</div><div class="line"><a name="l01850"></a><span class="lineno"> 1850</span>&#160;&lt;i&gt;`[-]CCYY-MM-DD[Z|(+|-)hh:mm]`&lt;/i&gt; with a time zone.</div><div class="line"><a name="l01851"></a><span class="lineno"> 1851</span>&#160;</div><div class="line"><a name="l01852"></a><span class="lineno"> 1852</span>&#160;The serializer ignores the time part and the deserializer only populates the</div><div class="line"><a name="l01853"></a><span class="lineno"> 1853</span>&#160;date part of the struct, setting the time to 00:00:00.  There is no unreasonable</div><div class="line"><a name="l01854"></a><span class="lineno"> 1854</span>&#160;limit on the date range because the year field is stored as an integer (`int`).</div><div class="line"><a name="l01855"></a><span class="lineno"> 1855</span>&#160;</div><div class="line"><a name="l01856"></a><span class="lineno"> 1856</span>&#160;An `unsigned long long` (`ULONG64` or `uint64_t`) type that contains a 24 hour</div><div class="line"><a name="l01857"></a><span class="lineno"> 1857</span>&#160;time in microseconds UTC is mapped to the built-in &lt;i&gt;`xsd:time`&lt;/i&gt; XSD type and</div><div class="line"><a name="l01858"></a><span class="lineno"> 1858</span>&#160;serialized with the custom serializer &lt;i&gt;`gsoap/custom/long_time.h`&lt;/i&gt; that declares a</div><div class="line"><a name="l01859"></a><span class="lineno"> 1859</span>&#160;`xsd__time` type:</div><div class="line"><a name="l01860"></a><span class="lineno"> 1860</span>&#160;</div><div class="line"><a name="l01861"></a><span class="lineno"> 1861</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01862"></a><span class="lineno"> 1862</span>&#160;    #import &quot;custom/long_time.h&quot; // import typedef unsigned long long xsd__time;</div><div class="line"><a name="l01863"></a><span class="lineno"> 1863</span>&#160;    ... // use xsd__time</div><div class="line"><a name="l01864"></a><span class="lineno"> 1864</span>&#160;~~~</div><div class="line"><a name="l01865"></a><span class="lineno"> 1865</span>&#160;</div><div class="line"><a name="l01866"></a><span class="lineno"> 1866</span>&#160;Compile and link your code with &lt;i&gt;`gsoap/custom/long_time.c`&lt;/i&gt;.</div><div class="line"><a name="l01867"></a><span class="lineno"> 1867</span>&#160;</div><div class="line"><a name="l01868"></a><span class="lineno"> 1868</span>&#160;This type represents `00:00:00.000000` to `23:59:59.999999`, from 0 to an</div><div class="line"><a name="l01869"></a><span class="lineno"> 1869</span>&#160;upper bound of 86,399,999,999.  A microsecond resolution means that a 1 second</div><div class="line"><a name="l01870"></a><span class="lineno"> 1870</span>&#160;increment requires an increment of 1,000,000 in the integer value.</div><div class="line"><a name="l01871"></a><span class="lineno"> 1871</span>&#160;</div><div class="line"><a name="l01872"></a><span class="lineno"> 1872</span>&#160;The XML value space of &lt;i&gt;`xsd:time`&lt;/i&gt; are points in time recurring each day of the</div><div class="line"><a name="l01873"></a><span class="lineno"> 1873</span>&#160;form &lt;i&gt;`hh:mm:ss.sss[Z|(+|-)hh:mm]`&lt;/i&gt;, where &lt;i&gt;`Z`&lt;/i&gt; is the UTC time zone or a time</div><div class="line"><a name="l01874"></a><span class="lineno"> 1874</span>&#160;zone offset from UTC is used.  The `xsd__time` value is always considered and</div><div class="line"><a name="l01875"></a><span class="lineno"> 1875</span>&#160;represented in UTC by the serializer.</div><div class="line"><a name="l01876"></a><span class="lineno"> 1876</span>&#160;</div><div class="line"><a name="l01877"></a><span class="lineno"> 1877</span>&#160;To convert date and/or time values to a string, we use the auto-generated</div><div class="line"><a name="l01878"></a><span class="lineno"> 1878</span>&#160;function for type `T`:</div><div class="line"><a name="l01879"></a><span class="lineno"> 1879</span>&#160;</div><div class="line"><a name="l01880"></a><span class="lineno"> 1880</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01881"></a><span class="lineno"> 1881</span>&#160;    const char *soap_T2s(struct soap*, T val)</div><div class="line"><a name="l01882"></a><span class="lineno"> 1882</span>&#160;~~~</div><div class="line"><a name="l01883"></a><span class="lineno"> 1883</span>&#160;</div><div class="line"><a name="l01884"></a><span class="lineno"> 1884</span>&#160;For date and time types `T`, the string returned is stored in an internal</div><div class="line"><a name="l01885"></a><span class="lineno"> 1885</span>&#160;buffer of the current `soap` context, so you should copy it to keep it from being</div><div class="line"><a name="l01886"></a><span class="lineno"> 1886</span>&#160;overwritten.  For example, use `char *soap_strdup(struct soap*, const char*)`.</div><div class="line"><a name="l01887"></a><span class="lineno"> 1887</span>&#160;</div><div class="line"><a name="l01888"></a><span class="lineno"> 1888</span>&#160;To convert a string to a date/time value, we use the auto-generated function</div><div class="line"><a name="l01889"></a><span class="lineno"> 1889</span>&#160;</div><div class="line"><a name="l01890"></a><span class="lineno"> 1890</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01891"></a><span class="lineno"> 1891</span>&#160;    int soap_s2T(struct soap*, const char *str, T *val)</div><div class="line"><a name="l01892"></a><span class="lineno"> 1892</span>&#160;~~~</div><div class="line"><a name="l01893"></a><span class="lineno"> 1893</span>&#160;  </div><div class="line"><a name="l01894"></a><span class="lineno"> 1894</span>&#160;where `T` is for example `dateTime` (for `time_t`), `xsd__dateTime` (for</div><div class="line"><a name="l01895"></a><span class="lineno"> 1895</span>&#160;`struct tm`, `struct timeval`, or `std::chrono::system_clock::time_point`).</div><div class="line"><a name="l01896"></a><span class="lineno"> 1896</span>&#160;The function `soap_s2T` returns `SOAP_OK` on success or an error when the value</div><div class="line"><a name="l01897"></a><span class="lineno"> 1897</span>&#160;is not a date/time.</div><div class="line"><a name="l01898"></a><span class="lineno"> 1898</span>&#160;</div><div class="line"><a name="l01899"></a><span class="lineno"> 1899</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l01900"></a><span class="lineno"> 1900</span>&#160;</div><div class="line"><a name="l01901"></a><span class="lineno"> 1901</span>&#160;Time duration types                                                    {#toxsd8}</div><div class="line"><a name="l01902"></a><span class="lineno"> 1902</span>&#160;-------------------</div><div class="line"><a name="l01903"></a><span class="lineno"> 1903</span>&#160;</div><div class="line"><a name="l01904"></a><span class="lineno"> 1904</span>&#160;The XML value space of &lt;i&gt;`xsd:duration`&lt;/i&gt; are values of the form &lt;i&gt;`PnYnMnDTnHnMnS`&lt;/i&gt;</div><div class="line"><a name="l01905"></a><span class="lineno"> 1905</span>&#160;where the capital letters are delimiters.  Delimiters may be omitted when the</div><div class="line"><a name="l01906"></a><span class="lineno"> 1906</span>&#160;corresponding member is not used.</div><div class="line"><a name="l01907"></a><span class="lineno"> 1907</span>&#160;</div><div class="line"><a name="l01908"></a><span class="lineno"> 1908</span>&#160;A `long long` (`LONG64` or `int64_t`) type that contains a duration (time</div><div class="line"><a name="l01909"></a><span class="lineno"> 1909</span>&#160;lapse) in milliseconds is mapped to the built-in &lt;i&gt;`xsd:duration`&lt;/i&gt; XSD type and</div><div class="line"><a name="l01910"></a><span class="lineno"> 1910</span>&#160;serialized with the custom serializer &lt;i&gt;`gsoap/custom/duration.h`&lt;/i&gt; that declares a</div><div class="line"><a name="l01911"></a><span class="lineno"> 1911</span>&#160;`xsd__duration` type:</div><div class="line"><a name="l01912"></a><span class="lineno"> 1912</span>&#160;</div><div class="line"><a name="l01913"></a><span class="lineno"> 1913</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01914"></a><span class="lineno"> 1914</span>&#160;    #import &quot;custom/duration.h&quot; // import typedef long long xsd__duration;</div><div class="line"><a name="l01915"></a><span class="lineno"> 1915</span>&#160;    ... // use xsd__duration</div><div class="line"><a name="l01916"></a><span class="lineno"> 1916</span>&#160;~~~</div><div class="line"><a name="l01917"></a><span class="lineno"> 1917</span>&#160;</div><div class="line"><a name="l01918"></a><span class="lineno"> 1918</span>&#160;Compile and link your code with &lt;i&gt;`gsoap/custom/duration.c`&lt;/i&gt;.</div><div class="line"><a name="l01919"></a><span class="lineno"> 1919</span>&#160;</div><div class="line"><a name="l01920"></a><span class="lineno"> 1920</span>&#160;The duration type `xsd__duration` can represent 106,751,991,167 days forward</div><div class="line"><a name="l01921"></a><span class="lineno"> 1921</span>&#160;and backward with millisecond precision.</div><div class="line"><a name="l01922"></a><span class="lineno"> 1922</span>&#160;</div><div class="line"><a name="l01923"></a><span class="lineno"> 1923</span>&#160;Durations that exceed a month are always output in days, rather than months to</div><div class="line"><a name="l01924"></a><span class="lineno"> 1924</span>&#160;avoid days-per-month conversion inacurracies.</div><div class="line"><a name="l01925"></a><span class="lineno"> 1925</span>&#160;</div><div class="line"><a name="l01926"></a><span class="lineno"> 1926</span>&#160;Durations that are received in years and months instead of total number of days</div><div class="line"><a name="l01927"></a><span class="lineno"> 1927</span>&#160;from a reference point are not well defined, since there is no accepted</div><div class="line"><a name="l01928"></a><span class="lineno"> 1928</span>&#160;reference time point (it may or may not be the current time).  The decoder</div><div class="line"><a name="l01929"></a><span class="lineno"> 1929</span>&#160;simple assumes that there are 30 days per month.  For example, conversion of</div><div class="line"><a name="l01930"></a><span class="lineno"> 1930</span>&#160;&quot;P4M&quot; gives 120 days.  Therefore, the durations &quot;P4M&quot; and &quot;P120D&quot; are assumed</div><div class="line"><a name="l01931"></a><span class="lineno"> 1931</span>&#160;to be identical, which is not necessarily true depending on the reference point</div><div class="line"><a name="l01932"></a><span class="lineno"> 1932</span>&#160;in time.</div><div class="line"><a name="l01933"></a><span class="lineno"> 1933</span>&#160;</div><div class="line"><a name="l01934"></a><span class="lineno"> 1934</span>&#160;Rescaling of the duration value by may be needed when adding the duration value</div><div class="line"><a name="l01935"></a><span class="lineno"> 1935</span>&#160;to a `time_t` value, because `time_t` may or may not have a seconds resolution,</div><div class="line"><a name="l01936"></a><span class="lineno"> 1936</span>&#160;depending on the platform and possible changes to `time_t`.</div><div class="line"><a name="l01937"></a><span class="lineno"> 1937</span>&#160;</div><div class="line"><a name="l01938"></a><span class="lineno"> 1938</span>&#160;Rescaling is done automatically when you add a C++11 `std::chrono::nanoseconds`</div><div class="line"><a name="l01939"></a><span class="lineno"> 1939</span>&#160;value to a `std::chrono::system_clock::time_point` value.  To use</div><div class="line"><a name="l01940"></a><span class="lineno"> 1940</span>&#160;`std::chrono::nanoseconds` as &lt;i&gt;`xsd:duration`&lt;/i&gt;:</div><div class="line"><a name="l01941"></a><span class="lineno"> 1941</span>&#160;</div><div class="line"><a name="l01942"></a><span class="lineno"> 1942</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01943"></a><span class="lineno"> 1943</span>&#160;    #import &quot;custom/chrono_duration.h&quot; // import typedef std::chrono::duration xsd__duration;</div><div class="line"><a name="l01944"></a><span class="lineno"> 1944</span>&#160;    ... // use xsd__duration</div><div class="line"><a name="l01945"></a><span class="lineno"> 1945</span>&#160;~~~</div><div class="line"><a name="l01946"></a><span class="lineno"> 1946</span>&#160;</div><div class="line"><a name="l01947"></a><span class="lineno"> 1947</span>&#160;Compile and link your code with &lt;i&gt;`gsoap/custom/chrono_duration.cpp`&lt;/i&gt;.</div><div class="line"><a name="l01948"></a><span class="lineno"> 1948</span>&#160;</div><div class="line"><a name="l01949"></a><span class="lineno"> 1949</span>&#160;This type can represent 384,307,168 days (2^63 nanoseconds) forwards and</div><div class="line"><a name="l01950"></a><span class="lineno"> 1950</span>&#160;backwards in time in increments of 1 ns (1/1000000000 second).</div><div class="line"><a name="l01951"></a><span class="lineno"> 1951</span>&#160;</div><div class="line"><a name="l01952"></a><span class="lineno"> 1952</span>&#160;The same observations with respect to receiving durations in years and months</div><div class="line"><a name="l01953"></a><span class="lineno"> 1953</span>&#160;apply to this serializer&#39;s decoder.</div><div class="line"><a name="l01954"></a><span class="lineno"> 1954</span>&#160;</div><div class="line"><a name="l01955"></a><span class="lineno"> 1955</span>&#160;To convert duration values to a string, we use the auto-generated function</div><div class="line"><a name="l01956"></a><span class="lineno"> 1956</span>&#160;</div><div class="line"><a name="l01957"></a><span class="lineno"> 1957</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01958"></a><span class="lineno"> 1958</span>&#160;    const char *soap_xsd__duration2s(struct soap*, xsd__duration val)</div><div class="line"><a name="l01959"></a><span class="lineno"> 1959</span>&#160;~~~</div><div class="line"><a name="l01960"></a><span class="lineno"> 1960</span>&#160;</div><div class="line"><a name="l01961"></a><span class="lineno"> 1961</span>&#160;The string returned is stored in an internal buffer, so you should copy it to</div><div class="line"><a name="l01962"></a><span class="lineno"> 1962</span>&#160;keep it from being overwritten,  Use `soap_strdup(struct soap*, const char*)`</div><div class="line"><a name="l01963"></a><span class="lineno"> 1963</span>&#160;for example to copy this string.</div><div class="line"><a name="l01964"></a><span class="lineno"> 1964</span>&#160;</div><div class="line"><a name="l01965"></a><span class="lineno"> 1965</span>&#160;To convert a string to a duration value, we use the auto-generated function</div><div class="line"><a name="l01966"></a><span class="lineno"> 1966</span>&#160;</div><div class="line"><a name="l01967"></a><span class="lineno"> 1967</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01968"></a><span class="lineno"> 1968</span>&#160;    int soap_s2xsd__dateTime(struct soap*, const char *str, xsd__dateTime *val)</div><div class="line"><a name="l01969"></a><span class="lineno"> 1969</span>&#160;~~~</div><div class="line"><a name="l01970"></a><span class="lineno"> 1970</span>&#160;</div><div class="line"><a name="l01971"></a><span class="lineno"> 1971</span>&#160;The function returns `SOAP_OK` on success or an error when the value is not a</div><div class="line"><a name="l01972"></a><span class="lineno"> 1972</span>&#160;duration.</div><div class="line"><a name="l01973"></a><span class="lineno"> 1973</span>&#160;</div><div class="line"><a name="l01974"></a><span class="lineno"> 1974</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l01975"></a><span class="lineno"> 1975</span>&#160;</div><div class="line"><a name="l01976"></a><span class="lineno"> 1976</span>&#160;Classes and structs                                                    {#toxsd9}</div><div class="line"><a name="l01977"></a><span class="lineno"> 1977</span>&#160;-------------------</div><div class="line"><a name="l01978"></a><span class="lineno"> 1978</span>&#160;</div><div class="line"><a name="l01979"></a><span class="lineno"> 1979</span>&#160;Classes and structs are mapped to XSD complexTypes.  The XML value space</div><div class="line"><a name="l01980"></a><span class="lineno"> 1980</span>&#160;consists of XML elements with attributes and subelements, possibly constrained</div><div class="line"><a name="l01981"></a><span class="lineno"> 1981</span>&#160;by XML schema validation rules that enforce element and attribute occurrence</div><div class="line"><a name="l01982"></a><span class="lineno"> 1982</span>&#160;contraints, numerical value range constraints, and string length and pattern</div><div class="line"><a name="l01983"></a><span class="lineno"> 1983</span>&#160;constraints.</div><div class="line"><a name="l01984"></a><span class="lineno"> 1984</span>&#160;</div><div class="line"><a name="l01985"></a><span class="lineno"> 1985</span>&#160;Classes that are declared with the gSOAP tools are limited to single</div><div class="line"><a name="l01986"></a><span class="lineno"> 1986</span>&#160;inheritence only.  The soapcpp2 tool does not allow structs to be inherited.</div><div class="line"><a name="l01987"></a><span class="lineno"> 1987</span>&#160;</div><div class="line"><a name="l01988"></a><span class="lineno"> 1988</span>&#160;The class and struct name is bound to an XML namespace by means of the prefix</div><div class="line"><a name="l01989"></a><span class="lineno"> 1989</span>&#160;naming convention or by using [colon notation](#toxsd1):</div><div class="line"><a name="l01990"></a><span class="lineno"> 1990</span>&#160;</div><div class="line"><a name="l01991"></a><span class="lineno"> 1991</span>&#160;~~~{.cpp}</div><div class="line"><a name="l01992"></a><span class="lineno"> 1992</span>&#160;    //gsoap ns schema namespace: urn:types</div><div class="line"><a name="l01993"></a><span class="lineno"> 1993</span>&#160;    class ns__record</div><div class="line"><a name="l01994"></a><span class="lineno"> 1994</span>&#160;    {</div><div class="line"><a name="l01995"></a><span class="lineno"> 1995</span>&#160;     public:</div><div class="line"><a name="l01996"></a><span class="lineno"> 1996</span>&#160;        std::string  name;</div><div class="line"><a name="l01997"></a><span class="lineno"> 1997</span>&#160;        uint64_t     SSN;</div><div class="line"><a name="l01998"></a><span class="lineno"> 1998</span>&#160;        ns__record  *spouse;</div><div class="line"><a name="l01999"></a><span class="lineno"> 1999</span>&#160;        ns__record();</div><div class="line"><a name="l02000"></a><span class="lineno"> 2000</span>&#160;        ~ns__record();</div><div class="line"><a name="l02001"></a><span class="lineno"> 2001</span>&#160;      protected:</div><div class="line"><a name="l02002"></a><span class="lineno"> 2002</span>&#160;        struct soap  *soap;</div><div class="line"><a name="l02003"></a><span class="lineno"> 2003</span>&#160;    };</div><div class="line"><a name="l02004"></a><span class="lineno"> 2004</span>&#160;~~~</div><div class="line"><a name="l02005"></a><span class="lineno"> 2005</span>&#160;</div><div class="line"><a name="l02006"></a><span class="lineno"> 2006</span>&#160;In the example above, we also added a context pointer to the `soap` context that</div><div class="line"><a name="l02007"></a><span class="lineno"> 2007</span>&#160;manages this instance.  It is set when the instance is created in the engine&#39;s</div><div class="line"><a name="l02008"></a><span class="lineno"> 2008</span>&#160;context, for example when deserialized and populated by the engine.</div><div class="line"><a name="l02009"></a><span class="lineno"> 2009</span>&#160;</div><div class="line"><a name="l02010"></a><span class="lineno"> 2010</span>&#160;The class maps to a complexType in the soapcpp2-generated XML schema:</div><div class="line"><a name="l02011"></a><span class="lineno"> 2011</span>&#160;</div><div class="line"><a name="l02012"></a><span class="lineno"> 2012</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l02013"></a><span class="lineno"> 2013</span>&#160;~~~{.xml}</div><div class="line"><a name="l02014"></a><span class="lineno"> 2014</span>&#160;    &lt;complexType name=&quot;record&quot;&gt;</div><div class="line"><a name="l02015"></a><span class="lineno"> 2015</span>&#160;      &lt;sequence&gt;</div><div class="line"><a name="l02016"></a><span class="lineno"> 2016</span>&#160;        &lt;element name=&quot;name&quot; type=&quot;xsd:string&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l02017"></a><span class="lineno"> 2017</span>&#160;        &lt;element name=&quot;SSN&quot; type=&quot;xsd:unsignedLong&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l02018"></a><span class="lineno"> 2018</span>&#160;        &lt;element name=&quot;spouse&quot; type=&quot;ns:record&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot; nillable=&quot;true&quot;/&gt;</div><div class="line"><a name="l02019"></a><span class="lineno"> 2019</span>&#160;      &lt;/sequence&gt;</div><div class="line"><a name="l02020"></a><span class="lineno"> 2020</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l02021"></a><span class="lineno"> 2021</span>&#160;~~~</div><div class="line"><a name="l02022"></a><span class="lineno"> 2022</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l02023"></a><span class="lineno"> 2023</span>&#160;</div><div class="line"><a name="l02024"></a><span class="lineno"> 2024</span>&#160;The following sections apply to both structs and classes.  Structs require the</div><div class="line"><a name="l02025"></a><span class="lineno"> 2025</span>&#160;use of the `struct` keyword with the struct name, otherwise soapcpp2 will throw</div><div class="line"><a name="l02026"></a><span class="lineno"> 2026</span>&#160;a syntax error.  As is often done in C, use a `typedef` to declare a `struct`</div><div class="line"><a name="l02027"></a><span class="lineno"> 2027</span>&#160;that can be used without the `struct` keyword.</div><div class="line"><a name="l02028"></a><span class="lineno"> 2028</span>&#160;</div><div class="line"><a name="l02029"></a><span class="lineno"> 2029</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l02030"></a><span class="lineno"> 2030</span>&#160;</div><div class="line"><a name="l02031"></a><span class="lineno"> 2031</span>&#160;### Serializable versus transient types and data members             {#toxsd9-1}</div><div class="line"><a name="l02032"></a><span class="lineno"> 2032</span>&#160;</div><div class="line"><a name="l02033"></a><span class="lineno"> 2033</span>&#160;Public data members of a class or struct are serializable when their types are</div><div class="line"><a name="l02034"></a><span class="lineno"> 2034</span>&#160;serializable.  Private and protected members are transient and not</div><div class="line"><a name="l02035"></a><span class="lineno"> 2035</span>&#160;serializable.</div><div class="line"><a name="l02036"></a><span class="lineno"> 2036</span>&#160;</div><div class="line"><a name="l02037"></a><span class="lineno"> 2037</span>&#160;Also `const` and `static` members are not serializable, with the exception of</div><div class="line"><a name="l02038"></a><span class="lineno"> 2038</span>&#160;`const char*` and `const wchar_t*`.  Types and specific class/struct members</div><div class="line"><a name="l02039"></a><span class="lineno"> 2039</span>&#160;can be made transient with the `extern` qualifier for types and by marking</div><div class="line"><a name="l02040"></a><span class="lineno"> 2040</span>&#160;members with `[` and `]`:</div><div class="line"><a name="l02041"></a><span class="lineno"> 2041</span>&#160;</div><div class="line"><a name="l02042"></a><span class="lineno"> 2042</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02043"></a><span class="lineno"> 2043</span>&#160;    extern class std::ostream;     // declare std::ostream transient</div><div class="line"><a name="l02044"></a><span class="lineno"> 2044</span>&#160;    class ns__record</div><div class="line"><a name="l02045"></a><span class="lineno"> 2045</span>&#160;    {</div><div class="line"><a name="l02046"></a><span class="lineno"> 2046</span>&#160;     public:</div><div class="line"><a name="l02047"></a><span class="lineno"> 2047</span>&#160;      [ int              num; ]      // not serialized: member is marked transient with [ ]</div><div class="line"><a name="l02048"></a><span class="lineno"> 2048</span>&#160;        std::ostream     out;        // not serialized: std:ostream is transient</div><div class="line"><a name="l02049"></a><span class="lineno"> 2049</span>&#160;        static const int MAX = 1024; // not serialized: static const member</div><div class="line"><a name="l02050"></a><span class="lineno"> 2050</span>&#160;      private:</div><div class="line"><a name="l02051"></a><span class="lineno"> 2051</span>&#160;        std::string      id;         // not serialized: private member</div><div class="line"><a name="l02052"></a><span class="lineno"> 2052</span>&#160;    };</div><div class="line"><a name="l02053"></a><span class="lineno"> 2053</span>&#160;~~~</div><div class="line"><a name="l02054"></a><span class="lineno"> 2054</span>&#160;</div><div class="line"><a name="l02055"></a><span class="lineno"> 2055</span>&#160;By declaring `std::ostream` transient with `extern` you can use this type</div><div class="line"><a name="l02056"></a><span class="lineno"> 2056</span>&#160;wherever you need it without soapcpp2 complaining that this class and any other </div><div class="line"><a name="l02057"></a><span class="lineno"> 2057</span>&#160;class or type declared as `extern` is not defined.  Do not use `extern` with</div><div class="line"><a name="l02058"></a><span class="lineno"> 2058</span>&#160;`typedef`, because this declares a custom serializer, see</div><div class="line"><a name="l02059"></a><span class="lineno"> 2059</span>&#160;[adding custom serializers](#custom).</div><div class="line"><a name="l02060"></a><span class="lineno"> 2060</span>&#160;</div><div class="line"><a name="l02061"></a><span class="lineno"> 2061</span>&#160;Marking members transient with `[` and `]` makes them transient (and visually</div><div class="line"><a name="l02062"></a><span class="lineno"> 2062</span>&#160;makes them stand out).  This has otherwise no effect on the generated code for</div><div class="line"><a name="l02063"></a><span class="lineno"> 2063</span>&#160;the class or struct to be used in your application code.</div><div class="line"><a name="l02064"></a><span class="lineno"> 2064</span>&#160;</div><div class="line"><a name="l02065"></a><span class="lineno"> 2065</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l02066"></a><span class="lineno"> 2066</span>&#160;</div><div class="line"><a name="l02067"></a><span class="lineno"> 2067</span>&#160;### Derived types in C++                                           {#toxsd9-1-1}</div><div class="line"><a name="l02068"></a><span class="lineno"> 2068</span>&#160;</div><div class="line"><a name="l02069"></a><span class="lineno"> 2069</span>&#160;Extensible and restricted types in XML schemas are derived types from single</div><div class="line"><a name="l02070"></a><span class="lineno"> 2070</span>&#160;simple and complex base types.  XML schema derived types are naturally</div><div class="line"><a name="l02071"></a><span class="lineno"> 2071</span>&#160;represented by C++ derived classes using single inheritance.  Besides the</div><div class="line"><a name="l02072"></a><span class="lineno"> 2072</span>&#160;concept of extensions versus restrictions, there are two kinds of derived</div><div class="line"><a name="l02073"></a><span class="lineno"> 2073</span>&#160;types: complexTypes with simpleContent, meaning types with XML CDATA values,</div><div class="line"><a name="l02074"></a><span class="lineno"> 2074</span>&#160;and complexTypes with complexContent, meaning types with sub-elements.  Both</div><div class="line"><a name="l02075"></a><span class="lineno"> 2075</span>&#160;are permitted to have one or more XML attributes.</div><div class="line"><a name="l02076"></a><span class="lineno"> 2076</span>&#160;</div><div class="line"><a name="l02077"></a><span class="lineno"> 2077</span>&#160;A complexType with simpleContent is defined as a wrapper to contain XML CDATA</div><div class="line"><a name="l02078"></a><span class="lineno"> 2078</span>&#160;values and any number of attributes, see</div><div class="line"><a name="l02079"></a><span class="lineno"> 2079</span>&#160;[wrapper class/struct with simpleContent](#toxsd10-4).</div><div class="line"><a name="l02080"></a><span class="lineno"> 2080</span>&#160;Wrapper class/struct types can form a hierarchy of derived types in C++ using</div><div class="line"><a name="l02081"></a><span class="lineno"> 2081</span>&#160;inheritance.  For example:</div><div class="line"><a name="l02082"></a><span class="lineno"> 2082</span>&#160;</div><div class="line"><a name="l02083"></a><span class="lineno"> 2083</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02084"></a><span class="lineno"> 2084</span>&#160;    class xsd__anyType</div><div class="line"><a name="l02085"></a><span class="lineno"> 2085</span>&#160;    {</div><div class="line"><a name="l02086"></a><span class="lineno"> 2086</span>&#160;     public:</div><div class="line"><a name="l02087"></a><span class="lineno"> 2087</span>&#160;        std::string __item; // string to hold any simpleContent</div><div class="line"><a name="l02088"></a><span class="lineno"> 2088</span>&#160;    };</div><div class="line"><a name="l02089"></a><span class="lineno"> 2089</span>&#160;    class ns__data : public xsd__anyType</div><div class="line"><a name="l02090"></a><span class="lineno"> 2090</span>&#160;    {</div><div class="line"><a name="l02091"></a><span class="lineno"> 2091</span>&#160;     public:</div><div class="line"><a name="l02092"></a><span class="lineno"> 2092</span>&#160;      @ std::string value 1; // extends xsd:anyType with a required attribute</div><div class="line"><a name="l02093"></a><span class="lineno"> 2093</span>&#160;    };</div><div class="line"><a name="l02094"></a><span class="lineno"> 2094</span>&#160;~~~</div><div class="line"><a name="l02095"></a><span class="lineno"> 2095</span>&#160;</div><div class="line"><a name="l02096"></a><span class="lineno"> 2096</span>&#160;The `ns__data` class maps to a complexType in the soapcpp2-generated XML schema:</div><div class="line"><a name="l02097"></a><span class="lineno"> 2097</span>&#160;</div><div class="line"><a name="l02098"></a><span class="lineno"> 2098</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l02099"></a><span class="lineno"> 2099</span>&#160;~~~{.xml}</div><div class="line"><a name="l02100"></a><span class="lineno"> 2100</span>&#160;    &lt;complexType name=&quot;string&quot;&gt;</div><div class="line"><a name="l02101"></a><span class="lineno"> 2101</span>&#160;      &lt;simpleContent&gt;</div><div class="line"><a name="l02102"></a><span class="lineno"> 2102</span>&#160;        &lt;extension base=&quot;xsd:string&quot;&gt;</div><div class="line"><a name="l02103"></a><span class="lineno"> 2103</span>&#160;          &lt;attribute name=&quot;value&quot; type=&quot;xsd:string&quot; use=&quot;required&quot;/&gt;</div><div class="line"><a name="l02104"></a><span class="lineno"> 2104</span>&#160;        &lt;/extension&gt;</div><div class="line"><a name="l02105"></a><span class="lineno"> 2105</span>&#160;      &lt;/simpleContent&gt;</div><div class="line"><a name="l02106"></a><span class="lineno"> 2106</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l02107"></a><span class="lineno"> 2107</span>&#160;~~~</div><div class="line"><a name="l02108"></a><span class="lineno"> 2108</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l02109"></a><span class="lineno"> 2109</span>&#160;</div><div class="line"><a name="l02110"></a><span class="lineno"> 2110</span>&#160;The XML value space consists of an element with the string contents an optional</div><div class="line"><a name="l02111"></a><span class="lineno"> 2111</span>&#160;attribute:</div><div class="line"><a name="l02112"></a><span class="lineno"> 2112</span>&#160;</div><div class="line"><a name="l02113"></a><span class="lineno"> 2113</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l02114"></a><span class="lineno"> 2114</span>&#160;~~~{.xml}</div><div class="line"><a name="l02115"></a><span class="lineno"> 2115</span>&#160;    &lt;ns:data value=&quot;abc&quot;&gt;xyz&lt;/ns:data&gt;</div><div class="line"><a name="l02116"></a><span class="lineno"> 2116</span>&#160;~~~</div><div class="line"><a name="l02117"></a><span class="lineno"> 2117</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l02118"></a><span class="lineno"> 2118</span>&#160;</div><div class="line"><a name="l02119"></a><span class="lineno"> 2119</span>&#160;By contrast, a complexType with complexContent typically extends a given base</div><div class="line"><a name="l02120"></a><span class="lineno"> 2120</span>&#160;complexType.  For example:</div><div class="line"><a name="l02121"></a><span class="lineno"> 2121</span>&#160;</div><div class="line"><a name="l02122"></a><span class="lineno"> 2122</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02123"></a><span class="lineno"> 2123</span>&#160;    class ns__base</div><div class="line"><a name="l02124"></a><span class="lineno"> 2124</span>&#160;    {</div><div class="line"><a name="l02125"></a><span class="lineno"> 2125</span>&#160;     public:</div><div class="line"><a name="l02126"></a><span class="lineno"> 2126</span>&#160;        std::string name   1;</div><div class="line"><a name="l02127"></a><span class="lineno"> 2127</span>&#160;        int         number 1;</div><div class="line"><a name="l02128"></a><span class="lineno"> 2128</span>&#160;    };</div><div class="line"><a name="l02129"></a><span class="lineno"> 2129</span>&#160;    class ns__derived : public ns__base</div><div class="line"><a name="l02130"></a><span class="lineno"> 2130</span>&#160;    {</div><div class="line"><a name="l02131"></a><span class="lineno"> 2131</span>&#160;     public:</div><div class="line"><a name="l02132"></a><span class="lineno"> 2132</span>&#160;      @ std::string value 1; // extends ns:base with an attribute</div><div class="line"><a name="l02133"></a><span class="lineno"> 2133</span>&#160;        std::string text  1; // extends ns:base with an element</div><div class="line"><a name="l02134"></a><span class="lineno"> 2134</span>&#160;    };</div><div class="line"><a name="l02135"></a><span class="lineno"> 2135</span>&#160;~~~</div><div class="line"><a name="l02136"></a><span class="lineno"> 2136</span>&#160;</div><div class="line"><a name="l02137"></a><span class="lineno"> 2137</span>&#160;The `ns__base` and `ns__derived` classes maps to complexTypes in the soapcpp2-generated XML schema:</div><div class="line"><a name="l02138"></a><span class="lineno"> 2138</span>&#160;</div><div class="line"><a name="l02139"></a><span class="lineno"> 2139</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l02140"></a><span class="lineno"> 2140</span>&#160;~~~{.xml}</div><div class="line"><a name="l02141"></a><span class="lineno"> 2141</span>&#160;    &lt;complexType name=&quot;base&quot;&gt;</div><div class="line"><a name="l02142"></a><span class="lineno"> 2142</span>&#160;      &lt;sequence&gt;</div><div class="line"><a name="l02143"></a><span class="lineno"> 2143</span>&#160;        &lt;element name=&quot;name&quot; type=&quot;xsd:string&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l02144"></a><span class="lineno"> 2144</span>&#160;        &lt;element name=&quot;number&quot; type=&quot;xsd:int&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l02145"></a><span class="lineno"> 2145</span>&#160;      &lt;/sequence&gt;</div><div class="line"><a name="l02146"></a><span class="lineno"> 2146</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l02147"></a><span class="lineno"> 2147</span>&#160;    &lt;complexType name=&quot;derived&quot;&gt;</div><div class="line"><a name="l02148"></a><span class="lineno"> 2148</span>&#160;      &lt;complexContent&gt;</div><div class="line"><a name="l02149"></a><span class="lineno"> 2149</span>&#160;        &lt;extension base=&quot;ns:base&quot;&gt;</div><div class="line"><a name="l02150"></a><span class="lineno"> 2150</span>&#160;          &lt;sequence&gt;</div><div class="line"><a name="l02151"></a><span class="lineno"> 2151</span>&#160;            &lt;element name=&quot;text&quot; type=&quot;xsd:string&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l02152"></a><span class="lineno"> 2152</span>&#160;          &lt;/sequence&gt;</div><div class="line"><a name="l02153"></a><span class="lineno"> 2153</span>&#160;        &lt;/extension&gt;</div><div class="line"><a name="l02154"></a><span class="lineno"> 2154</span>&#160;      &lt;/complexContent&gt;</div><div class="line"><a name="l02155"></a><span class="lineno"> 2155</span>&#160;      &lt;attribute name=&quot;value&quot; type=&quot;xsd:string&quot; use=&quot;required&quot;/&gt;</div><div class="line"><a name="l02156"></a><span class="lineno"> 2156</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l02157"></a><span class="lineno"> 2157</span>&#160;~~~</div><div class="line"><a name="l02158"></a><span class="lineno"> 2158</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l02159"></a><span class="lineno"> 2159</span>&#160;</div><div class="line"><a name="l02160"></a><span class="lineno"> 2160</span>&#160;The XML value space of `ns__derived` consists of three requires child elements</div><div class="line"><a name="l02161"></a><span class="lineno"> 2161</span>&#160;and an optional attribute:</div><div class="line"><a name="l02162"></a><span class="lineno"> 2162</span>&#160;</div><div class="line"><a name="l02163"></a><span class="lineno"> 2163</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l02164"></a><span class="lineno"> 2164</span>&#160;~~~{.xml}</div><div class="line"><a name="l02165"></a><span class="lineno"> 2165</span>&#160;    &lt;ns:derived value=&quot;abc&quot;&gt;</div><div class="line"><a name="l02166"></a><span class="lineno"> 2166</span>&#160;      &lt;name&gt;def&lt;/name&gt;</div><div class="line"><a name="l02167"></a><span class="lineno"> 2167</span>&#160;      &lt;number&gt;123&lt;/number&gt;</div><div class="line"><a name="l02168"></a><span class="lineno"> 2168</span>&#160;      &lt;text&gt;xyz&lt;/text&gt;</div><div class="line"><a name="l02169"></a><span class="lineno"> 2169</span>&#160;    &lt;/ns:derived&gt;</div><div class="line"><a name="l02170"></a><span class="lineno"> 2170</span>&#160;~~~</div><div class="line"><a name="l02171"></a><span class="lineno"> 2171</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l02172"></a><span class="lineno"> 2172</span>&#160;</div><div class="line"><a name="l02173"></a><span class="lineno"> 2173</span>&#160;Derived types can be used for two main purposes in XML schema by extending or</div><div class="line"><a name="l02174"></a><span class="lineno"> 2174</span>&#160;restricting base types.  One purpose is to reuse a base type when defining a</div><div class="line"><a name="l02175"></a><span class="lineno"> 2175</span>&#160;derived type, such that common parts do not need to be replicated.  The second</div><div class="line"><a name="l02176"></a><span class="lineno"> 2176</span>&#160;purpose is to be able to use a derived type in place of a base type in XML, which</div><div class="line"><a name="l02177"></a><span class="lineno"> 2177</span>&#160;is indicated by an &lt;i&gt;`xsi:type`&lt;/i&gt; attribute with the qualified name of the</div><div class="line"><a name="l02178"></a><span class="lineno"> 2178</span>&#160;derived type.  Consider for example the following class that uses the</div><div class="line"><a name="l02179"></a><span class="lineno"> 2179</span>&#160;previously declared base types `xsd__anyType` and `ns__base`:</div><div class="line"><a name="l02180"></a><span class="lineno"> 2180</span>&#160;</div><div class="line"><a name="l02181"></a><span class="lineno"> 2181</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02182"></a><span class="lineno"> 2182</span>&#160;    class ns__record</div><div class="line"><a name="l02183"></a><span class="lineno"> 2183</span>&#160;    {</div><div class="line"><a name="l02184"></a><span class="lineno"> 2184</span>&#160;     public:</div><div class="line"><a name="l02185"></a><span class="lineno"> 2185</span>&#160;        xsd__anyType *base1 1; // required element</div><div class="line"><a name="l02186"></a><span class="lineno"> 2186</span>&#160;        ns__base     *base2 1; // required element</div><div class="line"><a name="l02187"></a><span class="lineno"> 2187</span>&#160;    };</div><div class="line"><a name="l02188"></a><span class="lineno"> 2188</span>&#160;~~~</div><div class="line"><a name="l02189"></a><span class="lineno"> 2189</span>&#160;</div><div class="line"><a name="l02190"></a><span class="lineno"> 2190</span>&#160;We can assign base type values to the `ns_record` members:</div><div class="line"><a name="l02191"></a><span class="lineno"> 2191</span>&#160;</div><div class="line"><a name="l02192"></a><span class="lineno"> 2192</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02193"></a><span class="lineno"> 2193</span>&#160;    ns__record record;</div><div class="line"><a name="l02194"></a><span class="lineno"> 2194</span>&#160;    record.base1 = soap_new_xsd__anyType(soap);</div><div class="line"><a name="l02195"></a><span class="lineno"> 2195</span>&#160;    record.base2 = soap_new_ns__base(soap);</div><div class="line"><a name="l02196"></a><span class="lineno"> 2196</span>&#160;    soap_write_ns__record(soap, &amp;record);</div><div class="line"><a name="l02197"></a><span class="lineno"> 2197</span>&#160;~~~</div><div class="line"><a name="l02198"></a><span class="lineno"> 2198</span>&#160;</div><div class="line"><a name="l02199"></a><span class="lineno"> 2199</span>&#160;This produces the following XML fragment populated with default values (empty</div><div class="line"><a name="l02200"></a><span class="lineno"> 2200</span>&#160;text for strings and zeros for numbers), where element &lt;i&gt;`base1`&lt;/i&gt; has a</div><div class="line"><a name="l02201"></a><span class="lineno"> 2201</span>&#160;simpleContent value and element &lt;i&gt;`base2`&lt;/i&gt; has two child elements:</div><div class="line"><a name="l02202"></a><span class="lineno"> 2202</span>&#160;</div><div class="line"><a name="l02203"></a><span class="lineno"> 2203</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l02204"></a><span class="lineno"> 2204</span>&#160;~~~{.xml}</div><div class="line"><a name="l02205"></a><span class="lineno"> 2205</span>&#160;    &lt;ns:record&gt;</div><div class="line"><a name="l02206"></a><span class="lineno"> 2206</span>&#160;      &lt;base1&gt;&lt;/base1&gt;</div><div class="line"><a name="l02207"></a><span class="lineno"> 2207</span>&#160;      &lt;base2&gt;</div><div class="line"><a name="l02208"></a><span class="lineno"> 2208</span>&#160;        &lt;name&gt;&lt;/name&gt;</div><div class="line"><a name="l02209"></a><span class="lineno"> 2209</span>&#160;        &lt;number&gt;0&lt;/number&gt;</div><div class="line"><a name="l02210"></a><span class="lineno"> 2210</span>&#160;      &lt;/base2&gt;</div><div class="line"><a name="l02211"></a><span class="lineno"> 2211</span>&#160;    &lt;/ns:record&gt;</div><div class="line"><a name="l02212"></a><span class="lineno"> 2212</span>&#160;~~~</div><div class="line"><a name="l02213"></a><span class="lineno"> 2213</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l02214"></a><span class="lineno"> 2214</span>&#160;</div><div class="line"><a name="l02215"></a><span class="lineno"> 2215</span>&#160;We can also assign derived type values to the `ns_record` members:</div><div class="line"><a name="l02216"></a><span class="lineno"> 2216</span>&#160;</div><div class="line"><a name="l02217"></a><span class="lineno"> 2217</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02218"></a><span class="lineno"> 2218</span>&#160;    ns__record record;</div><div class="line"><a name="l02219"></a><span class="lineno"> 2219</span>&#160;    record.base1 = soap_new_ns__data(soap);</div><div class="line"><a name="l02220"></a><span class="lineno"> 2220</span>&#160;    record.base2 = soap_new_ns__derived(soap);</div><div class="line"><a name="l02221"></a><span class="lineno"> 2221</span>&#160;    soap_write_ns__record(soap, &amp;record);</div><div class="line"><a name="l02222"></a><span class="lineno"> 2222</span>&#160;~~~</div><div class="line"><a name="l02223"></a><span class="lineno"> 2223</span>&#160;</div><div class="line"><a name="l02224"></a><span class="lineno"> 2224</span>&#160;This produces the following XML fragment populated with default values (empty</div><div class="line"><a name="l02225"></a><span class="lineno"> 2225</span>&#160;text for strings and zeros for numbers), where element &lt;i&gt;`base1`&lt;/i&gt; has</div><div class="line"><a name="l02226"></a><span class="lineno"> 2226</span>&#160;schema type &lt;i&gt;`ns:data`&lt;/i&gt; with simpleContent and an attribute, and</div><div class="line"><a name="l02227"></a><span class="lineno"> 2227</span>&#160;&lt;i&gt;`base2`&lt;/i&gt; has schema type &lt;i&gt;`ns:derived`&lt;/i&gt; with three child elements</div><div class="line"><a name="l02228"></a><span class="lineno"> 2228</span>&#160;and an attribute:</div><div class="line"><a name="l02229"></a><span class="lineno"> 2229</span>&#160;</div><div class="line"><a name="l02230"></a><span class="lineno"> 2230</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l02231"></a><span class="lineno"> 2231</span>&#160;~~~{.xml}</div><div class="line"><a name="l02232"></a><span class="lineno"> 2232</span>&#160;    &lt;ns:record&gt;</div><div class="line"><a name="l02233"></a><span class="lineno"> 2233</span>&#160;      &lt;base1 xsi:type=&quot;ns:data&quot; value=&quot;&quot;&gt;&lt;/base1&gt;</div><div class="line"><a name="l02234"></a><span class="lineno"> 2234</span>&#160;      &lt;base2 xsi:type=&quot;ns:derived&quot; value=&quot;&quot;&gt;</div><div class="line"><a name="l02235"></a><span class="lineno"> 2235</span>&#160;        &lt;name&gt;&lt;/name&gt;</div><div class="line"><a name="l02236"></a><span class="lineno"> 2236</span>&#160;        &lt;number&gt;0&lt;/number&gt;</div><div class="line"><a name="l02237"></a><span class="lineno"> 2237</span>&#160;        &lt;text&gt;&lt;/text&gt;</div><div class="line"><a name="l02238"></a><span class="lineno"> 2238</span>&#160;      &lt;/base2&gt;</div><div class="line"><a name="l02239"></a><span class="lineno"> 2239</span>&#160;    &lt;/ns:record&gt;</div><div class="line"><a name="l02240"></a><span class="lineno"> 2240</span>&#160;~~~</div><div class="line"><a name="l02241"></a><span class="lineno"> 2241</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l02242"></a><span class="lineno"> 2242</span>&#160;</div><div class="line"><a name="l02243"></a><span class="lineno"> 2243</span>&#160;Deserialization automatically allocates and assigns a `ns__base` class instance to a</div><div class="line"><a name="l02244"></a><span class="lineno"> 2244</span>&#160;`ns__base` pointer when deserializing the &lt;i&gt;`ns:base`&lt;/i&gt; schema type and allocates and</div><div class="line"><a name="l02245"></a><span class="lineno"> 2245</span>&#160;assigns a `ns__derived` class instance to a `ns__base` pointer when deserializing the</div><div class="line"><a name="l02246"></a><span class="lineno"> 2246</span>&#160;&lt;i&gt;`ns:derived`&lt;/i&gt; type when an element with &lt;i&gt;`xsi:type=&quot;ns:derived&quot;`&lt;/i&gt; is</div><div class="line"><a name="l02247"></a><span class="lineno"> 2247</span>&#160;parsed.  All classes are extended by soapcpp2 by a `soap_type()` method that</div><div class="line"><a name="l02248"></a><span class="lineno"> 2248</span>&#160;returns the unique `SOAP_TYPE_T` value of the class `T`.  This makes it easy to</div><div class="line"><a name="l02249"></a><span class="lineno"> 2249</span>&#160;check whether the deserialized data contains a derived type to implement</div><div class="line"><a name="l02250"></a><span class="lineno"> 2250</span>&#160;type-safe code, for example:</div><div class="line"><a name="l02251"></a><span class="lineno"> 2251</span>&#160;</div><div class="line"><a name="l02252"></a><span class="lineno"> 2252</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02253"></a><span class="lineno"> 2253</span>&#160;    ns__record record;</div><div class="line"><a name="l02254"></a><span class="lineno"> 2254</span>&#160;    soap_read_ns__record(soap, &amp;record);</div><div class="line"><a name="l02255"></a><span class="lineno"> 2255</span>&#160;    if (record.base1-&gt;soap_type() == SOAP_TYPE_ns__data)</div><div class="line"><a name="l02256"></a><span class="lineno"> 2256</span>&#160;      std::cout &lt;&lt; &quot;Derived ns:data &quot;</div><div class="line"><a name="l02257"></a><span class="lineno"> 2257</span>&#160;                &lt;&lt; dynamic_cast&lt;ns__data*&gt;(record.base1)-&gt;value</div><div class="line"><a name="l02258"></a><span class="lineno"> 2258</span>&#160;                &lt;&lt; std::endl;</div><div class="line"><a name="l02259"></a><span class="lineno"> 2259</span>&#160;    else</div><div class="line"><a name="l02260"></a><span class="lineno"> 2260</span>&#160;      std::cout &lt;&lt; &quot;Base xsd:anyType&quot; &lt;&lt; std::endl;</div><div class="line"><a name="l02261"></a><span class="lineno"> 2261</span>&#160;    if (record.base2-&gt;soap_type() == SOAP_TYPE_ns__derived)</div><div class="line"><a name="l02262"></a><span class="lineno"> 2262</span>&#160;      std::cout &lt;&lt; &quot;Derived ns:derived &quot;</div><div class="line"><a name="l02263"></a><span class="lineno"> 2263</span>&#160;                &lt;&lt; dynamic_cast&lt;ns__derived*&gt;(record.base2)-&gt;value</div><div class="line"><a name="l02264"></a><span class="lineno"> 2264</span>&#160;                &lt;&lt; std::endl;</div><div class="line"><a name="l02265"></a><span class="lineno"> 2265</span>&#160;    else</div><div class="line"><a name="l02266"></a><span class="lineno"> 2266</span>&#160;      std::cout &lt;&lt; &quot;Base ns:base&quot; &lt;&lt; std::endl;</div><div class="line"><a name="l02267"></a><span class="lineno"> 2267</span>&#160;~~~</div><div class="line"><a name="l02268"></a><span class="lineno"> 2268</span>&#160;</div><div class="line"><a name="l02269"></a><span class="lineno"> 2269</span>&#160;This example should use the `SOAP_XML_STRICT` mode flag to initialize the</div><div class="line"><a name="l02270"></a><span class="lineno"> 2270</span>&#160;`soap` context to ensure that all required values are present in the</div><div class="line"><a name="l02271"></a><span class="lineno"> 2271</span>&#160;deserialized structures.</div><div class="line"><a name="l02272"></a><span class="lineno"> 2272</span>&#160;</div><div class="line"><a name="l02273"></a><span class="lineno"> 2273</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l02274"></a><span class="lineno"> 2274</span>&#160;</div><div class="line"><a name="l02275"></a><span class="lineno"> 2275</span>&#160;### Derived types in C                                             {#toxsd9-1-2}</div><div class="line"><a name="l02276"></a><span class="lineno"> 2276</span>&#160;</div><div class="line"><a name="l02277"></a><span class="lineno"> 2277</span>&#160;While single inheritance works well in C++ to represent derived types as we</div><div class="line"><a name="l02278"></a><span class="lineno"> 2278</span>&#160;discussed in the previous section, this will obviously not work in C.  Two</div><div class="line"><a name="l02279"></a><span class="lineno"> 2279</span>&#160;methods to serialize derived types in C are presented here.  The first method</div><div class="line"><a name="l02280"></a><span class="lineno"> 2280</span>&#160;uses `void*` to serialize anything.  The second method is more accurate and is</div><div class="line"><a name="l02281"></a><span class="lineno"> 2281</span>&#160;relatively new in gSOAP.</div><div class="line"><a name="l02282"></a><span class="lineno"> 2282</span>&#160;</div><div class="line"><a name="l02283"></a><span class="lineno"> 2283</span>&#160;To serialize any type is possible with [tagged void pointer members](#toxsd9-12) to</div><div class="line"><a name="l02284"></a><span class="lineno"> 2284</span>&#160;serialize data pointed to by a `void*` member, which can be any serializable</div><div class="line"><a name="l02285"></a><span class="lineno"> 2285</span>&#160;type, such as derived types.  For `void*` deserialization to work the XML</div><div class="line"><a name="l02286"></a><span class="lineno"> 2286</span>&#160;parsed must contain an &lt;i&gt;`xsi:type`&lt;/i&gt; attribute with a schema type.  Only</div><div class="line"><a name="l02287"></a><span class="lineno"> 2287</span>&#160;then can the deserializer instantiate the corresponding serializable C/C++</div><div class="line"><a name="l02288"></a><span class="lineno"> 2288</span>&#160;type.  Base types serialized do not require an &lt;i&gt;`xsi:type`&lt;/i&gt; to indicate</div><div class="line"><a name="l02289"></a><span class="lineno"> 2289</span>&#160;the base schema type, so this approach is not guaranteed to work and requires a</div><div class="line"><a name="l02290"></a><span class="lineno"> 2290</span>&#160;workaround with an anonymous wrapper struct/class that contains both the base</div><div class="line"><a name="l02291"></a><span class="lineno"> 2291</span>&#160;type and a `void*`.  For example:</div><div class="line"><a name="l02292"></a><span class="lineno"> 2292</span>&#160;</div><div class="line"><a name="l02293"></a><span class="lineno"> 2293</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02294"></a><span class="lineno"> 2294</span>&#160;    struct ns__base // a base type</div><div class="line"><a name="l02295"></a><span class="lineno"> 2295</span>&#160;    {</div><div class="line"><a name="l02296"></a><span class="lineno"> 2296</span>&#160;        char *name   1;</div><div class="line"><a name="l02297"></a><span class="lineno"> 2297</span>&#160;        int   number 1;</div><div class="line"><a name="l02298"></a><span class="lineno"> 2298</span>&#160;    };</div><div class="line"><a name="l02299"></a><span class="lineno"> 2299</span>&#160;    struct ns__derived // extends ns__base with two additional members</div><div class="line"><a name="l02300"></a><span class="lineno"> 2300</span>&#160;    {</div><div class="line"><a name="l02301"></a><span class="lineno"> 2301</span>&#160;        char  *name   1;</div><div class="line"><a name="l02302"></a><span class="lineno"> 2302</span>&#160;        int    number 1;</div><div class="line"><a name="l02303"></a><span class="lineno"> 2303</span>&#160;        char  *text   1;</div><div class="line"><a name="l02304"></a><span class="lineno"> 2304</span>&#160;      @ char *value   1;</div><div class="line"><a name="l02305"></a><span class="lineno"> 2305</span>&#160;    };</div><div class="line"><a name="l02306"></a><span class="lineno"> 2306</span>&#160;    struct __ns__base // a wrapper, not visible in XML</div><div class="line"><a name="l02307"></a><span class="lineno"> 2307</span>&#160;    {</div><div class="line"><a name="l02308"></a><span class="lineno"> 2308</span>&#160;        int __type;              // the SOAP_TYPE_T pointed to by __self</div><div class="line"><a name="l02309"></a><span class="lineno"> 2309</span>&#160;        void *__self;            // points to any type</div><div class="line"><a name="l02310"></a><span class="lineno"> 2310</span>&#160;        struct ns__base *__self; // wraps ns__base for the current element tag</div><div class="line"><a name="l02311"></a><span class="lineno"> 2311</span>&#160;    }</div><div class="line"><a name="l02312"></a><span class="lineno"> 2312</span>&#160;    class ns__record</div><div class="line"><a name="l02313"></a><span class="lineno"> 2313</span>&#160;    {</div><div class="line"><a name="l02314"></a><span class="lineno"> 2314</span>&#160;      struct __ns__base base;</div><div class="line"><a name="l02315"></a><span class="lineno"> 2315</span>&#160;    };</div><div class="line"><a name="l02316"></a><span class="lineno"> 2316</span>&#160;~~~</div><div class="line"><a name="l02317"></a><span class="lineno"> 2317</span>&#160;</div><div class="line"><a name="l02318"></a><span class="lineno"> 2318</span>&#160;The `__ns__base` wrapper wraps the `ns__base` type to (de)serialize the</div><div class="line"><a name="l02319"></a><span class="lineno"> 2319</span>&#160;&lt;i&gt;`base`&lt;/i&gt; element that has no &lt;i&gt;`xsi:type`&lt;/i&gt; attribute and uses `void*`</div><div class="line"><a name="l02320"></a><span class="lineno"> 2320</span>&#160;to (de)serialize the &lt;i&gt;`base`&lt;/i&gt; element that has &lt;i&gt;`xsi:type`&lt;/i&gt;</div><div class="line"><a name="l02321"></a><span class="lineno"> 2321</span>&#160;attribute.  This works fine at the XML parsing level, but the generated</div><div class="line"><a name="l02322"></a><span class="lineno"> 2322</span>&#160;XML schema components do not accurately represent the derived type, because it</div><div class="line"><a name="l02323"></a><span class="lineno"> 2323</span>&#160;lacks the extension/restriction of the derived type (and the `__ns__base`</div><div class="line"><a name="l02324"></a><span class="lineno"> 2324</span>&#160;wrapper is invisible).</div><div class="line"><a name="l02325"></a><span class="lineno"> 2325</span>&#160;</div><div class="line"><a name="l02326"></a><span class="lineno"> 2326</span>&#160;Using `void*` to represent derived types in a base type wrapper is not very</div><div class="line"><a name="l02327"></a><span class="lineno"> 2327</span>&#160;accurate because we can serialize anything, not just derived types of a given</div><div class="line"><a name="l02328"></a><span class="lineno"> 2328</span>&#160;base type.  The wrapper may also hold two values: the base type value and a</div><div class="line"><a name="l02329"></a><span class="lineno"> 2329</span>&#160;derived type value.  Furthermore, using arrays or containers that hold base and</div><div class="line"><a name="l02330"></a><span class="lineno"> 2330</span>&#160;derived types becomes quite tricky because an array item could hold both the</div><div class="line"><a name="l02331"></a><span class="lineno"> 2331</span>&#160;base and derived type.</div><div class="line"><a name="l02332"></a><span class="lineno"> 2332</span>&#160;</div><div class="line"><a name="l02333"></a><span class="lineno"> 2333</span>&#160;As of gSOAP version 2.8.75, `wsdl2h -F` option `-F` generates base type structs</div><div class="line"><a name="l02334"></a><span class="lineno"> 2334</span>&#160;extended with transient pointer members to its derived types.  To serialize the</div><div class="line"><a name="l02335"></a><span class="lineno"> 2335</span>&#160;base type itself, all of the pointer members are NULL. If one of the pointer</div><div class="line"><a name="l02336"></a><span class="lineno"> 2336</span>&#160;members points to a derived type the derived type is serialized instead.</div><div class="line"><a name="l02337"></a><span class="lineno"> 2337</span>&#160;Deserialization is automatic, in that the base type is deserialized if the</div><div class="line"><a name="l02338"></a><span class="lineno"> 2338</span>&#160;element has no &lt;i&gt;`xsi:type`&lt;/i&gt; attribute or the attribute is the base schema</div><div class="line"><a name="l02339"></a><span class="lineno"> 2339</span>&#160;type, and a derived type is deserialized if the element has an</div><div class="line"><a name="l02340"></a><span class="lineno"> 2340</span>&#160;&lt;i&gt;`xsi&gt;type`&lt;/i&gt; attribute with the derived schema type.</div><div class="line"><a name="l02341"></a><span class="lineno"> 2341</span>&#160;</div><div class="line"><a name="l02342"></a><span class="lineno"> 2342</span>&#160;This method is fully automated for the wsdl2h tool to generate an interface</div><div class="line"><a name="l02343"></a><span class="lineno"> 2343</span>&#160;header file for soapcpp2 with the type derivations in C.  To use this method to</div><div class="line"><a name="l02344"></a><span class="lineno"> 2344</span>&#160;generate code from WSDLs and XSDs, use `wsdl2h -F` option `-F`.  This also</div><div class="line"><a name="l02345"></a><span class="lineno"> 2345</span>&#160;works in C++ if desired, but C++ inheritance works fine without this method.</div><div class="line"><a name="l02346"></a><span class="lineno"> 2346</span>&#160;</div><div class="line"><a name="l02347"></a><span class="lineno"> 2347</span>&#160;Using this method with soapcpp2 alone using a manually-specified interface</div><div class="line"><a name="l02348"></a><span class="lineno"> 2348</span>&#160;header file produces the specified type inheritance in the soapcpp2-generated</div><div class="line"><a name="l02349"></a><span class="lineno"> 2349</span>&#160;WSDL and XML schema files as complexType extensions.</div><div class="line"><a name="l02350"></a><span class="lineno"> 2350</span>&#160;</div><div class="line"><a name="l02351"></a><span class="lineno"> 2351</span>&#160;The soapcpp2 tool warns if a derived type has multiple base types.  At most one</div><div class="line"><a name="l02352"></a><span class="lineno"> 2352</span>&#160;base type for a derived type may be specified.</div><div class="line"><a name="l02353"></a><span class="lineno"> 2353</span>&#160;</div><div class="line"><a name="l02354"></a><span class="lineno"> 2354</span>&#160;This method with transient pointers to derived types makes it easy to use base</div><div class="line"><a name="l02355"></a><span class="lineno"> 2355</span>&#160;and derived types in C:</div><div class="line"><a name="l02356"></a><span class="lineno"> 2356</span>&#160;</div><div class="line"><a name="l02357"></a><span class="lineno"> 2357</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02358"></a><span class="lineno"> 2358</span>&#160;    struct ns__base // a base type</div><div class="line"><a name="l02359"></a><span class="lineno"> 2359</span>&#160;    {</div><div class="line"><a name="l02360"></a><span class="lineno"> 2360</span>&#160;        char *name   1;</div><div class="line"><a name="l02361"></a><span class="lineno"> 2361</span>&#160;        int   number 1;</div><div class="line"><a name="l02362"></a><span class="lineno"> 2362</span>&#160;      [ struct ns__derived *ns__derived; ] // points to derived type if non-NULL</div><div class="line"><a name="l02363"></a><span class="lineno"> 2363</span>&#160;    };</div><div class="line"><a name="l02364"></a><span class="lineno"> 2364</span>&#160;    struct ns__derived // extends ns__base with two additional members</div><div class="line"><a name="l02365"></a><span class="lineno"> 2365</span>&#160;    {</div><div class="line"><a name="l02366"></a><span class="lineno"> 2366</span>&#160;        char  *name   1;</div><div class="line"><a name="l02367"></a><span class="lineno"> 2367</span>&#160;        int    number 1;</div><div class="line"><a name="l02368"></a><span class="lineno"> 2368</span>&#160;        char  *text   1;</div><div class="line"><a name="l02369"></a><span class="lineno"> 2369</span>&#160;      @ char *value   1;</div><div class="line"><a name="l02370"></a><span class="lineno"> 2370</span>&#160;    };</div><div class="line"><a name="l02371"></a><span class="lineno"> 2371</span>&#160;    struct ns__record</div><div class="line"><a name="l02372"></a><span class="lineno"> 2372</span>&#160;    {</div><div class="line"><a name="l02373"></a><span class="lineno"> 2373</span>&#160;        struct ns__base base; // contains base type or derived type value</div><div class="line"><a name="l02374"></a><span class="lineno"> 2374</span>&#160;    };</div><div class="line"><a name="l02375"></a><span class="lineno"> 2375</span>&#160;~~~</div><div class="line"><a name="l02376"></a><span class="lineno"> 2376</span>&#160;</div><div class="line"><a name="l02377"></a><span class="lineno"> 2377</span>&#160;The `ns__base` struct includes the special member `ns__derived` that points to</div><div class="line"><a name="l02378"></a><span class="lineno"> 2378</span>&#160;a `ns__derived` value.  This special member must be:</div><div class="line"><a name="l02379"></a><span class="lineno"> 2379</span>&#160;</div><div class="line"><a name="l02380"></a><span class="lineno"> 2380</span>&#160;- a transient member (i.e. non-serializable) by placing the declaration within</div><div class="line"><a name="l02381"></a><span class="lineno"> 2381</span>&#160;  `[` and `]`, and</div><div class="line"><a name="l02382"></a><span class="lineno"> 2382</span>&#160;- the member name must match the type name (to be more precise, at least the</div><div class="line"><a name="l02383"></a><span class="lineno"> 2383</span>&#160;  initial part of the member name must match the type name as in the example</div><div class="line"><a name="l02384"></a><span class="lineno"> 2384</span>&#160;  `ns__derived_` works too).</div><div class="line"><a name="l02385"></a><span class="lineno"> 2385</span>&#160;</div><div class="line"><a name="l02386"></a><span class="lineno"> 2386</span>&#160;To serialize the `ns__base` value requires the `ns__derived` member to be NULL.</div><div class="line"><a name="l02387"></a><span class="lineno"> 2387</span>&#160;To serialize the `ns__derived` value requires the `ns__derived` member to point</div><div class="line"><a name="l02388"></a><span class="lineno"> 2388</span>&#160;to the `ns__derived` value to serialize and the `ns__base` members are</div><div class="line"><a name="l02389"></a><span class="lineno"> 2389</span>&#160;irrelevant.</div><div class="line"><a name="l02390"></a><span class="lineno"> 2390</span>&#160;</div><div class="line"><a name="l02391"></a><span class="lineno"> 2391</span>&#160;We can assign the base type value to the `ns_record::base` member:</div><div class="line"><a name="l02392"></a><span class="lineno"> 2392</span>&#160;</div><div class="line"><a name="l02393"></a><span class="lineno"> 2393</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02394"></a><span class="lineno"> 2394</span>&#160;    struct ns__record record;</div><div class="line"><a name="l02395"></a><span class="lineno"> 2395</span>&#160;    soap_default_ns__record(soap, &amp;record);</div><div class="line"><a name="l02396"></a><span class="lineno"> 2396</span>&#160;    soap_write_ns__record(soap, &amp;record);</div><div class="line"><a name="l02397"></a><span class="lineno"> 2397</span>&#160;~~~</div><div class="line"><a name="l02398"></a><span class="lineno"> 2398</span>&#160;</div><div class="line"><a name="l02399"></a><span class="lineno"> 2399</span>&#160;This produces the following XML fragment populated with default values (empty</div><div class="line"><a name="l02400"></a><span class="lineno"> 2400</span>&#160;text for strings and zeros for numbers), where element &lt;i&gt;`base`&lt;/i&gt; has two</div><div class="line"><a name="l02401"></a><span class="lineno"> 2401</span>&#160;child elements:</div><div class="line"><a name="l02402"></a><span class="lineno"> 2402</span>&#160;</div><div class="line"><a name="l02403"></a><span class="lineno"> 2403</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l02404"></a><span class="lineno"> 2404</span>&#160;~~~{.xml}</div><div class="line"><a name="l02405"></a><span class="lineno"> 2405</span>&#160;    &lt;ns:record&gt;</div><div class="line"><a name="l02406"></a><span class="lineno"> 2406</span>&#160;      &lt;base&gt;</div><div class="line"><a name="l02407"></a><span class="lineno"> 2407</span>&#160;        &lt;name&gt;&lt;/name&gt;</div><div class="line"><a name="l02408"></a><span class="lineno"> 2408</span>&#160;        &lt;number&gt;0&lt;/number&gt;</div><div class="line"><a name="l02409"></a><span class="lineno"> 2409</span>&#160;      &lt;/base&gt;</div><div class="line"><a name="l02410"></a><span class="lineno"> 2410</span>&#160;    &lt;/ns:record&gt;</div><div class="line"><a name="l02411"></a><span class="lineno"> 2411</span>&#160;~~~</div><div class="line"><a name="l02412"></a><span class="lineno"> 2412</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l02413"></a><span class="lineno"> 2413</span>&#160;</div><div class="line"><a name="l02414"></a><span class="lineno"> 2414</span>&#160;We can also assign the derived type value to the `ns_record::base` member:</div><div class="line"><a name="l02415"></a><span class="lineno"> 2415</span>&#160;</div><div class="line"><a name="l02416"></a><span class="lineno"> 2416</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02417"></a><span class="lineno"> 2417</span>&#160;    struct ns__record record;</div><div class="line"><a name="l02418"></a><span class="lineno"> 2418</span>&#160;    soap_default_ns__record(soap, &amp;record);</div><div class="line"><a name="l02419"></a><span class="lineno"> 2419</span>&#160;    record.base.ns__derived = soap_new_ns__derived(soap, -1);</div><div class="line"><a name="l02420"></a><span class="lineno"> 2420</span>&#160;    soap_write_ns__record(soap, &amp;record);</div><div class="line"><a name="l02421"></a><span class="lineno"> 2421</span>&#160;~~~</div><div class="line"><a name="l02422"></a><span class="lineno"> 2422</span>&#160;</div><div class="line"><a name="l02423"></a><span class="lineno"> 2423</span>&#160;This produces the following XML fragment populated with default values (empty</div><div class="line"><a name="l02424"></a><span class="lineno"> 2424</span>&#160;text for strings and zeros for numbers), where element &lt;i&gt;`base`&lt;/i&gt; has schema</div><div class="line"><a name="l02425"></a><span class="lineno"> 2425</span>&#160;type &lt;i&gt;`ns:derived`&lt;/i&gt; with three child elements and an attribute:</div><div class="line"><a name="l02426"></a><span class="lineno"> 2426</span>&#160;</div><div class="line"><a name="l02427"></a><span class="lineno"> 2427</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l02428"></a><span class="lineno"> 2428</span>&#160;~~~{.xml}</div><div class="line"><a name="l02429"></a><span class="lineno"> 2429</span>&#160;    &lt;ns:record&gt;</div><div class="line"><a name="l02430"></a><span class="lineno"> 2430</span>&#160;      &lt;base xsi:type=&quot;ns:derived&quot; value=&quot;&quot;&gt;</div><div class="line"><a name="l02431"></a><span class="lineno"> 2431</span>&#160;        &lt;name&gt;&lt;/name&gt;</div><div class="line"><a name="l02432"></a><span class="lineno"> 2432</span>&#160;        &lt;number&gt;0&lt;/number&gt;</div><div class="line"><a name="l02433"></a><span class="lineno"> 2433</span>&#160;        &lt;text&gt;&lt;/text&gt;</div><div class="line"><a name="l02434"></a><span class="lineno"> 2434</span>&#160;      &lt;/base&gt;</div><div class="line"><a name="l02435"></a><span class="lineno"> 2435</span>&#160;    &lt;/ns:record&gt;</div><div class="line"><a name="l02436"></a><span class="lineno"> 2436</span>&#160;~~~</div><div class="line"><a name="l02437"></a><span class="lineno"> 2437</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l02438"></a><span class="lineno"> 2438</span>&#160;</div><div class="line"><a name="l02439"></a><span class="lineno"> 2439</span>&#160;Deserialization automatically assigns values to the base members for the</div><div class="line"><a name="l02440"></a><span class="lineno"> 2440</span>&#160;`ns__base` type and populates the `ns__derived` member when a derived type with</div><div class="line"><a name="l02441"></a><span class="lineno"> 2441</span>&#160;&lt;i&gt;`xsi:type=&quot;ns:derived&quot;`&lt;/i&gt; is parsed.  This makes it easy to decompose the</div><div class="line"><a name="l02442"></a><span class="lineno"> 2442</span>&#160;deserialized data:</div><div class="line"><a name="l02443"></a><span class="lineno"> 2443</span>&#160;</div><div class="line"><a name="l02444"></a><span class="lineno"> 2444</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02445"></a><span class="lineno"> 2445</span>&#160;    struct ns__record record;</div><div class="line"><a name="l02446"></a><span class="lineno"> 2446</span>&#160;    soap_read_ns__record(soap, &amp;record);</div><div class="line"><a name="l02447"></a><span class="lineno"> 2447</span>&#160;    if (record.ns__derived)</div><div class="line"><a name="l02448"></a><span class="lineno"> 2448</span>&#160;      printf(&quot;Derived type with name=%s number=%d text=%s value=%s\n&quot;,</div><div class="line"><a name="l02449"></a><span class="lineno"> 2449</span>&#160;          record.ns__derived-&gt;name,</div><div class="line"><a name="l02450"></a><span class="lineno"> 2450</span>&#160;          record.ns__derived-&gt;number,</div><div class="line"><a name="l02451"></a><span class="lineno"> 2451</span>&#160;          record.ns__derived-&gt;text,</div><div class="line"><a name="l02452"></a><span class="lineno"> 2452</span>&#160;          record.ns__derived-&gt;value);</div><div class="line"><a name="l02453"></a><span class="lineno"> 2453</span>&#160;    else</div><div class="line"><a name="l02454"></a><span class="lineno"> 2454</span>&#160;      printf(&quot;Base type with name=%s number=%d\n&quot;,</div><div class="line"><a name="l02455"></a><span class="lineno"> 2455</span>&#160;          record.name,</div><div class="line"><a name="l02456"></a><span class="lineno"> 2456</span>&#160;          record.number);</div><div class="line"><a name="l02457"></a><span class="lineno"> 2457</span>&#160;~~~</div><div class="line"><a name="l02458"></a><span class="lineno"> 2458</span>&#160;</div><div class="line"><a name="l02459"></a><span class="lineno"> 2459</span>&#160;This example requires the `SOAP_XML_STRICT` mode flag to initialize the `soap`</div><div class="line"><a name="l02460"></a><span class="lineno"> 2460</span>&#160;context to ensure that all required values are present in the deserialized</div><div class="line"><a name="l02461"></a><span class="lineno"> 2461</span>&#160;structures, otherwise the `char*` strings may be NULL since XML validation</div><div class="line"><a name="l02462"></a><span class="lineno"> 2462</span>&#160;constraints are not enforced on the XML input.</div><div class="line"><a name="l02463"></a><span class="lineno"> 2463</span>&#160;</div><div class="line"><a name="l02464"></a><span class="lineno"> 2464</span>&#160;Deeper levels of simulated inheritance are possible, for example:</div><div class="line"><a name="l02465"></a><span class="lineno"> 2465</span>&#160;</div><div class="line"><a name="l02466"></a><span class="lineno"> 2466</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02467"></a><span class="lineno"> 2467</span>&#160;    struct ns__base // a base type</div><div class="line"><a name="l02468"></a><span class="lineno"> 2468</span>&#160;    {</div><div class="line"><a name="l02469"></a><span class="lineno"> 2469</span>&#160;        char *name   1;</div><div class="line"><a name="l02470"></a><span class="lineno"> 2470</span>&#160;        int   number 1;</div><div class="line"><a name="l02471"></a><span class="lineno"> 2471</span>&#160;      [ struct ns__derived *ns__derived; ] // points to derived type if non-NULL</div><div class="line"><a name="l02472"></a><span class="lineno"> 2472</span>&#160;    };</div><div class="line"><a name="l02473"></a><span class="lineno"> 2473</span>&#160;    struct ns__derived // extends ns__base with two additional members</div><div class="line"><a name="l02474"></a><span class="lineno"> 2474</span>&#160;    {</div><div class="line"><a name="l02475"></a><span class="lineno"> 2475</span>&#160;        char  *name   1;</div><div class="line"><a name="l02476"></a><span class="lineno"> 2476</span>&#160;        int    number 1;</div><div class="line"><a name="l02477"></a><span class="lineno"> 2477</span>&#160;        char  *text   1;</div><div class="line"><a name="l02478"></a><span class="lineno"> 2478</span>&#160;      @ char *value   1;</div><div class="line"><a name="l02479"></a><span class="lineno"> 2479</span>&#160;      [ struct ns__derived_derived *ns__derived_derived; ] // points to derived_derived type if non-NULL</div><div class="line"><a name="l02480"></a><span class="lineno"> 2480</span>&#160;    };</div><div class="line"><a name="l02481"></a><span class="lineno"> 2481</span>&#160;    struct ns__derived_derived // extends ns__derived with an additional member</div><div class="line"><a name="l02482"></a><span class="lineno"> 2482</span>&#160;    {</div><div class="line"><a name="l02483"></a><span class="lineno"> 2483</span>&#160;        char  *name   1;</div><div class="line"><a name="l02484"></a><span class="lineno"> 2484</span>&#160;        int    number 1;</div><div class="line"><a name="l02485"></a><span class="lineno"> 2485</span>&#160;        char  *text   1;</div><div class="line"><a name="l02486"></a><span class="lineno"> 2486</span>&#160;      @ char *value   1;</div><div class="line"><a name="l02487"></a><span class="lineno"> 2487</span>&#160;      @ char *type    1;</div><div class="line"><a name="l02488"></a><span class="lineno"> 2488</span>&#160;    };</div><div class="line"><a name="l02489"></a><span class="lineno"> 2489</span>&#160;~~~</div><div class="line"><a name="l02490"></a><span class="lineno"> 2490</span>&#160;</div><div class="line"><a name="l02491"></a><span class="lineno"> 2491</span>&#160;This requires two pointer traversals from the base type `ns__base` via</div><div class="line"><a name="l02492"></a><span class="lineno"> 2492</span>&#160;`ns__derived` to reach `ns__derived_derived`.</div><div class="line"><a name="l02493"></a><span class="lineno"> 2493</span>&#160;</div><div class="line"><a name="l02494"></a><span class="lineno"> 2494</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l02495"></a><span class="lineno"> 2495</span>&#160;</div><div class="line"><a name="l02496"></a><span class="lineno"> 2496</span>&#160;### Volatile classes and structs                                     {#toxsd9-2}</div><div class="line"><a name="l02497"></a><span class="lineno"> 2497</span>&#160;</div><div class="line"><a name="l02498"></a><span class="lineno"> 2498</span>&#160;Classes and structs can be declared `volatile` in the interface header file for</div><div class="line"><a name="l02499"></a><span class="lineno"> 2499</span>&#160;soapcpp2, which only has meaning for the gSOAP tools.  This annotation means</div><div class="line"><a name="l02500"></a><span class="lineno"> 2500</span>&#160;that these types are already declared elsewhere in your project&#39;s source code</div><div class="line"><a name="l02501"></a><span class="lineno"> 2501</span>&#160;and you do not want soapcpp2 to generate code with a second declaration of</div><div class="line"><a name="l02502"></a><span class="lineno"> 2502</span>&#160;these types.</div><div class="line"><a name="l02503"></a><span class="lineno"> 2503</span>&#160;</div><div class="line"><a name="l02504"></a><span class="lineno"> 2504</span>&#160;For example, `struct tm` is declared in the &lt;i&gt;`time.h`&lt;/i&gt; library.  You can</div><div class="line"><a name="l02505"></a><span class="lineno"> 2505</span>&#160;make it serializable and include a partial list of data members that you want</div><div class="line"><a name="l02506"></a><span class="lineno"> 2506</span>&#160;to serialize:</div><div class="line"><a name="l02507"></a><span class="lineno"> 2507</span>&#160;</div><div class="line"><a name="l02508"></a><span class="lineno"> 2508</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02509"></a><span class="lineno"> 2509</span>&#160;    volatile struct tm</div><div class="line"><a name="l02510"></a><span class="lineno"> 2510</span>&#160;    {</div><div class="line"><a name="l02511"></a><span class="lineno"> 2511</span>&#160;        int tm_sec;  // seconds (0 - 60)</div><div class="line"><a name="l02512"></a><span class="lineno"> 2512</span>&#160;        int tm_min;  // minutes (0 - 59)</div><div class="line"><a name="l02513"></a><span class="lineno"> 2513</span>&#160;        int tm_hour; // hours (0 - 23)</div><div class="line"><a name="l02514"></a><span class="lineno"> 2514</span>&#160;        int tm_mday; // day of month (1 - 31)</div><div class="line"><a name="l02515"></a><span class="lineno"> 2515</span>&#160;        int tm_mon;  // month of year (0 - 11)</div><div class="line"><a name="l02516"></a><span class="lineno"> 2516</span>&#160;        int tm_year; // year - 1900</div><div class="line"><a name="l02517"></a><span class="lineno"> 2517</span>&#160;    };</div><div class="line"><a name="l02518"></a><span class="lineno"> 2518</span>&#160;~~~</div><div class="line"><a name="l02519"></a><span class="lineno"> 2519</span>&#160;</div><div class="line"><a name="l02520"></a><span class="lineno"> 2520</span>&#160;You can declare classes and structs `volatile` for any such types you want to</div><div class="line"><a name="l02521"></a><span class="lineno"> 2521</span>&#160;serialize by only providing the public data members you want to serialize.</div><div class="line"><a name="l02522"></a><span class="lineno"> 2522</span>&#160;</div><div class="line"><a name="l02523"></a><span class="lineno"> 2523</span>&#160;In addition, [colon notation](#toxsd2) is a simple and effective way to bind an</div><div class="line"><a name="l02524"></a><span class="lineno"> 2524</span>&#160;existing class or struct to a schema.  For example, you can change the `tm` name</div><div class="line"><a name="l02525"></a><span class="lineno"> 2525</span>&#160;as follows without affecting the code that uses `struct tm` generated by</div><div class="line"><a name="l02526"></a><span class="lineno"> 2526</span>&#160;soapcpp2:</div><div class="line"><a name="l02527"></a><span class="lineno"> 2527</span>&#160;</div><div class="line"><a name="l02528"></a><span class="lineno"> 2528</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02529"></a><span class="lineno"> 2529</span>&#160;    volatile struct ns:tm { ... }</div><div class="line"><a name="l02530"></a><span class="lineno"> 2530</span>&#160;~~~</div><div class="line"><a name="l02531"></a><span class="lineno"> 2531</span>&#160;</div><div class="line"><a name="l02532"></a><span class="lineno"> 2532</span>&#160;This struct maps to a complexType in the soapcpp2-generated XML schema:</div><div class="line"><a name="l02533"></a><span class="lineno"> 2533</span>&#160;</div><div class="line"><a name="l02534"></a><span class="lineno"> 2534</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l02535"></a><span class="lineno"> 2535</span>&#160;~~~{.xml}</div><div class="line"><a name="l02536"></a><span class="lineno"> 2536</span>&#160;    &lt;complexType name=&quot;tm&quot;&gt;</div><div class="line"><a name="l02537"></a><span class="lineno"> 2537</span>&#160;      &lt;sequence&gt;</div><div class="line"><a name="l02538"></a><span class="lineno"> 2538</span>&#160;        &lt;element name=&quot;tm-sec&quot; type=&quot;xsd:int&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l02539"></a><span class="lineno"> 2539</span>&#160;        &lt;element name=&quot;tm-min&quot; type=&quot;xsd:int&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l02540"></a><span class="lineno"> 2540</span>&#160;        &lt;element name=&quot;tm-hour&quot; type=&quot;xsd:int&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l02541"></a><span class="lineno"> 2541</span>&#160;        &lt;element name=&quot;tm-mday&quot; type=&quot;xsd:int&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l02542"></a><span class="lineno"> 2542</span>&#160;        &lt;element name=&quot;tm-mon&quot; type=&quot;xsd:int&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l02543"></a><span class="lineno"> 2543</span>&#160;        &lt;element name=&quot;tm-year&quot; type=&quot;xsd:int&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l02544"></a><span class="lineno"> 2544</span>&#160;      &lt;/sequence&gt;</div><div class="line"><a name="l02545"></a><span class="lineno"> 2545</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l02546"></a><span class="lineno"> 2546</span>&#160;~~~</div><div class="line"><a name="l02547"></a><span class="lineno"> 2547</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l02548"></a><span class="lineno"> 2548</span>&#160;</div><div class="line"><a name="l02549"></a><span class="lineno"> 2549</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l02550"></a><span class="lineno"> 2550</span>&#160;</div><div class="line"><a name="l02551"></a><span class="lineno"> 2551</span>&#160;### Mutable classes and structs                                      {#toxsd9-3}</div><div class="line"><a name="l02552"></a><span class="lineno"> 2552</span>&#160;</div><div class="line"><a name="l02553"></a><span class="lineno"> 2553</span>&#160;Classes and structs can be declared `mutable` with the gSOAP tools.  This means</div><div class="line"><a name="l02554"></a><span class="lineno"> 2554</span>&#160;that their definition can be spread out over the source code.  This promotes the</div><div class="line"><a name="l02555"></a><span class="lineno"> 2555</span>&#160;concept of a class or struct as a *row of named values*, also known as a *named</div><div class="line"><a name="l02556"></a><span class="lineno"> 2556</span>&#160;tuple*, that can be extended at compile time in your source code with additional</div><div class="line"><a name="l02557"></a><span class="lineno"> 2557</span>&#160;members.  Because these types differ from the traditional object-oriented</div><div class="line"><a name="l02558"></a><span class="lineno"> 2558</span>&#160;principles and design concepts of classes and objects, constructors and</div><div class="line"><a name="l02559"></a><span class="lineno"> 2559</span>&#160;destructors cannot be defined (also because we cannot guarantee merging these</div><div class="line"><a name="l02560"></a><span class="lineno"> 2560</span>&#160;into one such that all members will be initialized).  A default constructor,</div><div class="line"><a name="l02561"></a><span class="lineno"> 2561</span>&#160;copy constructor, assignment operation, and destructor will be assigned</div><div class="line"><a name="l02562"></a><span class="lineno"> 2562</span>&#160;automatically by soapcpp2.</div><div class="line"><a name="l02563"></a><span class="lineno"> 2563</span>&#160;</div><div class="line"><a name="l02564"></a><span class="lineno"> 2564</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02565"></a><span class="lineno"> 2565</span>&#160;    mutable struct ns__tuple</div><div class="line"><a name="l02566"></a><span class="lineno"> 2566</span>&#160;    {</div><div class="line"><a name="l02567"></a><span class="lineno"> 2567</span>&#160;      @ std::string id;</div><div class="line"><a name="l02568"></a><span class="lineno"> 2568</span>&#160;    };</div><div class="line"><a name="l02569"></a><span class="lineno"> 2569</span>&#160;</div><div class="line"><a name="l02570"></a><span class="lineno"> 2570</span>&#160;    mutable struct ns__tuple</div><div class="line"><a name="l02571"></a><span class="lineno"> 2571</span>&#160;    {</div><div class="line"><a name="l02572"></a><span class="lineno"> 2572</span>&#160;        std::string name;</div><div class="line"><a name="l02573"></a><span class="lineno"> 2573</span>&#160;        std::string value;</div><div class="line"><a name="l02574"></a><span class="lineno"> 2574</span>&#160;    };</div><div class="line"><a name="l02575"></a><span class="lineno"> 2575</span>&#160;~~~</div><div class="line"><a name="l02576"></a><span class="lineno"> 2576</span>&#160;</div><div class="line"><a name="l02577"></a><span class="lineno"> 2577</span>&#160;The members are collected into one definition generated by soapcpp2.  Members</div><div class="line"><a name="l02578"></a><span class="lineno"> 2578</span>&#160;may be repeated from one definition to another, but only if their associated</div><div class="line"><a name="l02579"></a><span class="lineno"> 2579</span>&#160;types are identical.  So, for example, a third extension with a `value` member</div><div class="line"><a name="l02580"></a><span class="lineno"> 2580</span>&#160;with a different type fails:</div><div class="line"><a name="l02581"></a><span class="lineno"> 2581</span>&#160;</div><div class="line"><a name="l02582"></a><span class="lineno"> 2582</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02583"></a><span class="lineno"> 2583</span>&#160;    mutable struct ns__tuple</div><div class="line"><a name="l02584"></a><span class="lineno"> 2584</span>&#160;    {</div><div class="line"><a name="l02585"></a><span class="lineno"> 2585</span>&#160;        float value; // BAD: value is already declared std::string</div><div class="line"><a name="l02586"></a><span class="lineno"> 2586</span>&#160;    };</div><div class="line"><a name="l02587"></a><span class="lineno"> 2587</span>&#160;~~~</div><div class="line"><a name="l02588"></a><span class="lineno"> 2588</span>&#160;</div><div class="line"><a name="l02589"></a><span class="lineno"> 2589</span>&#160;The `mutable` concept has proven to be very useful when declaring and</div><div class="line"><a name="l02590"></a><span class="lineno"> 2590</span>&#160;collecting SOAP Headers for multiple services, which are collected into one</div><div class="line"><a name="l02591"></a><span class="lineno"> 2591</span>&#160;`struct SOAP_ENV__Header` by the soapcpp2 tool.</div><div class="line"><a name="l02592"></a><span class="lineno"> 2592</span>&#160;</div><div class="line"><a name="l02593"></a><span class="lineno"> 2593</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l02594"></a><span class="lineno"> 2594</span>&#160;</div><div class="line"><a name="l02595"></a><span class="lineno"> 2595</span>&#160;### Default and fixed member values                                  {#toxsd9-4}</div><div class="line"><a name="l02596"></a><span class="lineno"> 2596</span>&#160;</div><div class="line"><a name="l02597"></a><span class="lineno"> 2597</span>&#160;Class and struct data members in C and C++ may be declared with an optional</div><div class="line"><a name="l02598"></a><span class="lineno"> 2598</span>&#160;default initialization value that is provided &quot;inline&quot; with the declaration of</div><div class="line"><a name="l02599"></a><span class="lineno"> 2599</span>&#160;the member:</div><div class="line"><a name="l02600"></a><span class="lineno"> 2600</span>&#160;</div><div class="line"><a name="l02601"></a><span class="lineno"> 2601</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02602"></a><span class="lineno"> 2602</span>&#160;    class ns__record</div><div class="line"><a name="l02603"></a><span class="lineno"> 2603</span>&#160;    {</div><div class="line"><a name="l02604"></a><span class="lineno"> 2604</span>&#160;     public:</div><div class="line"><a name="l02605"></a><span class="lineno"> 2605</span>&#160;        std::string name = &quot;Joe&quot;;</div><div class="line"><a name="l02606"></a><span class="lineno"> 2606</span>&#160;        ...</div><div class="line"><a name="l02607"></a><span class="lineno"> 2607</span>&#160;    };</div><div class="line"><a name="l02608"></a><span class="lineno"> 2608</span>&#160;~~~</div><div class="line"><a name="l02609"></a><span class="lineno"> 2609</span>&#160;</div><div class="line"><a name="l02610"></a><span class="lineno"> 2610</span>&#160;Alternatively, you can use C++11 default initialization syntax:</div><div class="line"><a name="l02611"></a><span class="lineno"> 2611</span>&#160;</div><div class="line"><a name="l02612"></a><span class="lineno"> 2612</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02613"></a><span class="lineno"> 2613</span>&#160;    class ns__record</div><div class="line"><a name="l02614"></a><span class="lineno"> 2614</span>&#160;    {</div><div class="line"><a name="l02615"></a><span class="lineno"> 2615</span>&#160;     public:</div><div class="line"><a name="l02616"></a><span class="lineno"> 2616</span>&#160;        std::string name { &quot;Joe&quot; };</div><div class="line"><a name="l02617"></a><span class="lineno"> 2617</span>&#160;        ...</div><div class="line"><a name="l02618"></a><span class="lineno"> 2618</span>&#160;    };</div><div class="line"><a name="l02619"></a><span class="lineno"> 2619</span>&#160;~~~</div><div class="line"><a name="l02620"></a><span class="lineno"> 2620</span>&#160;</div><div class="line"><a name="l02621"></a><span class="lineno"> 2621</span>&#160;Any member with a primitive type can be initialized in this way.</div><div class="line"><a name="l02622"></a><span class="lineno"> 2622</span>&#160;</div><div class="line"><a name="l02623"></a><span class="lineno"> 2623</span>&#160;These initializations are performed by the default constructor that is added by</div><div class="line"><a name="l02624"></a><span class="lineno"> 2624</span>&#160;soapcpp2 to each class and struct (in C++ only).  A constructor is only added</div><div class="line"><a name="l02625"></a><span class="lineno"> 2625</span>&#160;when a default constructor is not already defined with the class declaration.</div><div class="line"><a name="l02626"></a><span class="lineno"> 2626</span>&#160;</div><div class="line"><a name="l02627"></a><span class="lineno"> 2627</span>&#160;You can explicitly (re)initialize an object with these initial values by using</div><div class="line"><a name="l02628"></a><span class="lineno"> 2628</span>&#160;the soapcpp2 auto-generated functions:</div><div class="line"><a name="l02629"></a><span class="lineno"> 2629</span>&#160;</div><div class="line"><a name="l02630"></a><span class="lineno"> 2630</span>&#160;- `void T::soap_default(struct soap*)` for `class T` (C++ only)</div><div class="line"><a name="l02631"></a><span class="lineno"> 2631</span>&#160;</div><div class="line"><a name="l02632"></a><span class="lineno"> 2632</span>&#160;- `void soap_default_T(struct soap*, T*)` for `struct T` (C and C++).</div><div class="line"><a name="l02633"></a><span class="lineno"> 2633</span>&#160;</div><div class="line"><a name="l02634"></a><span class="lineno"> 2634</span>&#160;If `T` is a struct or class that has a `soap` pointer member to a `::soap`</div><div class="line"><a name="l02635"></a><span class="lineno"> 2635</span>&#160;context then this pointer member will be set to the first argument passed to</div><div class="line"><a name="l02636"></a><span class="lineno"> 2636</span>&#160;these functions to initialize their `soap` pointer member.</div><div class="line"><a name="l02637"></a><span class="lineno"> 2637</span>&#160;</div><div class="line"><a name="l02638"></a><span class="lineno"> 2638</span>&#160;Default value initializations can be provided for members that have primitive</div><div class="line"><a name="l02639"></a><span class="lineno"> 2639</span>&#160;types (`bool`, `enum`, `time_t`, numeric and string types).</div><div class="line"><a name="l02640"></a><span class="lineno"> 2640</span>&#160;</div><div class="line"><a name="l02641"></a><span class="lineno"> 2641</span>&#160;Default value initializations of pointer members is permitted, but the effect</div><div class="line"><a name="l02642"></a><span class="lineno"> 2642</span>&#160;is different.  To conform to XML schema validation, an attribute member that is</div><div class="line"><a name="l02643"></a><span class="lineno"> 2643</span>&#160;a pointer to a primitive type will be assigned the default value when parsed</div><div class="line"><a name="l02644"></a><span class="lineno"> 2644</span>&#160;from XML.  An element member that is a pointer to a primitive type will be</div><div class="line"><a name="l02645"></a><span class="lineno"> 2645</span>&#160;assigned when the element is empty when parsed from XML.</div><div class="line"><a name="l02646"></a><span class="lineno"> 2646</span>&#160;</div><div class="line"><a name="l02647"></a><span class="lineno"> 2647</span>&#160;As of gSOAP 2.8.48 and greater, a fixed value can be assigned with a `==`.  A</div><div class="line"><a name="l02648"></a><span class="lineno"> 2648</span>&#160;fixed value is also verified by the parser&#39;s validator.</div><div class="line"><a name="l02649"></a><span class="lineno"> 2649</span>&#160;</div><div class="line"><a name="l02650"></a><span class="lineno"> 2650</span>&#160;Default and fixed values for members with or without pointers are best</div><div class="line"><a name="l02651"></a><span class="lineno"> 2651</span>&#160;explained with the following two example fragments.</div><div class="line"><a name="l02652"></a><span class="lineno"> 2652</span>&#160;</div><div class="line"><a name="l02653"></a><span class="lineno"> 2653</span>&#160;A record class with default values for `std::string` (or `std::wstring`)</div><div class="line"><a name="l02654"></a><span class="lineno"> 2654</span>&#160;attributes and elements is declared as follows:</div><div class="line"><a name="l02655"></a><span class="lineno"> 2655</span>&#160;</div><div class="line"><a name="l02656"></a><span class="lineno"> 2656</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02657"></a><span class="lineno"> 2657</span>&#160;    class ns__record_with_default</div><div class="line"><a name="l02658"></a><span class="lineno"> 2658</span>&#160;    {</div><div class="line"><a name="l02659"></a><span class="lineno"> 2659</span>&#160;     public:</div><div class="line"><a name="l02660"></a><span class="lineno"> 2660</span>&#160;      @ std::string  a   = &quot;A&quot;; // optional XML attribute with default value &quot;A&quot;</div><div class="line"><a name="l02661"></a><span class="lineno"> 2661</span>&#160;      @ std::string  b 1 = &quot;B&quot;; // required XML attribute with default value &quot;B&quot;</div><div class="line"><a name="l02662"></a><span class="lineno"> 2662</span>&#160;      @ std::string *c   = &quot;C&quot;; // optional XML attribute with default value &quot;C&quot;</div><div class="line"><a name="l02663"></a><span class="lineno"> 2663</span>&#160;        std::string  d 0 = &quot;D&quot;; // optional XML element with default value &quot;D&quot;</div><div class="line"><a name="l02664"></a><span class="lineno"> 2664</span>&#160;        std::string  e   = &quot;E&quot;; // required XML element with default value &quot;E&quot;</div><div class="line"><a name="l02665"></a><span class="lineno"> 2665</span>&#160;        std::string *f   = &quot;F&quot;; // optional XML element with default value &quot;F&quot;</div><div class="line"><a name="l02666"></a><span class="lineno"> 2666</span>&#160;        ...</div><div class="line"><a name="l02667"></a><span class="lineno"> 2667</span>&#160;    };</div><div class="line"><a name="l02668"></a><span class="lineno"> 2668</span>&#160;~~~</div><div class="line"><a name="l02669"></a><span class="lineno"> 2669</span>&#160;</div><div class="line"><a name="l02670"></a><span class="lineno"> 2670</span>&#160;Also `std::unique_ptr` and `std::shared_ptr` may be used instead of a regular</div><div class="line"><a name="l02671"></a><span class="lineno"> 2671</span>&#160;pointer to strings.</div><div class="line"><a name="l02672"></a><span class="lineno"> 2672</span>&#160;</div><div class="line"><a name="l02673"></a><span class="lineno"> 2673</span>&#160;With C `char*` (or `const char*`, `const wchar_t*`) strings in a struct, this</div><div class="line"><a name="l02674"></a><span class="lineno"> 2674</span>&#160;becomes:</div><div class="line"><a name="l02675"></a><span class="lineno"> 2675</span>&#160;</div><div class="line"><a name="l02676"></a><span class="lineno"> 2676</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02677"></a><span class="lineno"> 2677</span>&#160;    struct ns__record_with_default</div><div class="line"><a name="l02678"></a><span class="lineno"> 2678</span>&#160;    {</div><div class="line"><a name="l02679"></a><span class="lineno"> 2679</span>&#160;      @ char* a   = &quot;A&quot;; // optional XML attribute with default value &quot;A&quot;</div><div class="line"><a name="l02680"></a><span class="lineno"> 2680</span>&#160;      @ char* b 1 = &quot;B&quot;; // required XML attribute with default value &quot;B&quot;</div><div class="line"><a name="l02681"></a><span class="lineno"> 2681</span>&#160;        char* e 1 = &quot;E&quot;; // required XML element with default value &quot;E&quot;</div><div class="line"><a name="l02682"></a><span class="lineno"> 2682</span>&#160;        char* f   = &quot;F&quot;; // optional XML element with default value &quot;F&quot;</div><div class="line"><a name="l02683"></a><span class="lineno"> 2683</span>&#160;        ...</div><div class="line"><a name="l02684"></a><span class="lineno"> 2684</span>&#160;    };</div><div class="line"><a name="l02685"></a><span class="lineno"> 2685</span>&#160;~~~</div><div class="line"><a name="l02686"></a><span class="lineno"> 2686</span>&#160;</div><div class="line"><a name="l02687"></a><span class="lineno"> 2687</span>&#160;By contrast to `std::string e`, `char* e` must be marked `1` to make it</div><div class="line"><a name="l02688"></a><span class="lineno"> 2688</span>&#160;required, because pointer members are optional by default.</div><div class="line"><a name="l02689"></a><span class="lineno"> 2689</span>&#160;</div><div class="line"><a name="l02690"></a><span class="lineno"> 2690</span>&#160;Attributes are considered optional by default, unless marked as required with</div><div class="line"><a name="l02691"></a><span class="lineno"> 2691</span>&#160;the occurrence constraint `1`.  Elements are considered required unless the</div><div class="line"><a name="l02692"></a><span class="lineno"> 2692</span>&#160;member type is a pointer or if the member is marked optional with occurrence</div><div class="line"><a name="l02693"></a><span class="lineno"> 2693</span>&#160;constraint `0`.</div><div class="line"><a name="l02694"></a><span class="lineno"> 2694</span>&#160;</div><div class="line"><a name="l02695"></a><span class="lineno"> 2695</span>&#160;Instead of default values, fixed values indicate that the attribute or element</div><div class="line"><a name="l02696"></a><span class="lineno"> 2696</span>&#160;must contain that value, and only that value, when provided in XML.  A fixed</div><div class="line"><a name="l02697"></a><span class="lineno"> 2697</span>&#160;value is specified with a `==`.</div><div class="line"><a name="l02698"></a><span class="lineno"> 2698</span>&#160;</div><div class="line"><a name="l02699"></a><span class="lineno"> 2699</span>&#160;Attributes with default or fixed values may be omitted in XML.  When absent,</div><div class="line"><a name="l02700"></a><span class="lineno"> 2700</span>&#160;the default/fixed value is used at the receiving side, i.e. the deserializer</div><div class="line"><a name="l02701"></a><span class="lineno"> 2701</span>&#160;assigns the default/fixed value when the attribute is absent.  Therefore, there</div><div class="line"><a name="l02702"></a><span class="lineno"> 2702</span>&#160;is no need to make attributes with default/fixed values pointer based, because</div><div class="line"><a name="l02703"></a><span class="lineno"> 2703</span>&#160;there is no way to distinguish an omitted attribute from a populated attribute</div><div class="line"><a name="l02704"></a><span class="lineno"> 2704</span>&#160;on the receiving side.  The `c` member in the example above can be a</div><div class="line"><a name="l02705"></a><span class="lineno"> 2705</span>&#160;non-pointer for this reason.  The wsdl2h tool does not generate pointers for</div><div class="line"><a name="l02706"></a><span class="lineno"> 2706</span>&#160;attributes with default/fixed values.</div><div class="line"><a name="l02707"></a><span class="lineno"> 2707</span>&#160;</div><div class="line"><a name="l02708"></a><span class="lineno"> 2708</span>&#160;Elements with default or fixed values may be optional and the use of</div><div class="line"><a name="l02709"></a><span class="lineno"> 2709</span>&#160;default/fixed values with elements differs from attributes.  The default/fixed</div><div class="line"><a name="l02710"></a><span class="lineno"> 2710</span>&#160;value of an element is only used for elements that are empty in the XML payload</div><div class="line"><a name="l02711"></a><span class="lineno"> 2711</span>&#160;received.  Omitted optional elements in the XML payload received are simply</div><div class="line"><a name="l02712"></a><span class="lineno"> 2712</span>&#160;absent; no default/fixed value is assigned.</div><div class="line"><a name="l02713"></a><span class="lineno"> 2713</span>&#160;</div><div class="line"><a name="l02714"></a><span class="lineno"> 2714</span>&#160;@note gSOAP 2.8.106 and greater treat `char*` and `wchar_t*` with explicit</div><div class="line"><a name="l02715"></a><span class="lineno"> 2715</span>&#160;default and fixed values differently than previous versions.  Versions prior to</div><div class="line"><a name="l02716"></a><span class="lineno"> 2716</span>&#160;2.8.106 assign the default value when the corresponding XML element is absent,</div><div class="line"><a name="l02717"></a><span class="lineno"> 2717</span>&#160;whereas 2.8.106 and greater assign NULL when the XML element is absent, exactly</div><div class="line"><a name="l02718"></a><span class="lineno"> 2718</span>&#160;as documented in this updated version of this document.  To revert to the old</div><div class="line"><a name="l02719"></a><span class="lineno"> 2719</span>&#160;behavior, use &lt;b&gt;`soapcpp2 -z4`&lt;/b&gt; option &lt;b&gt;`-z4`&lt;/b&gt;.  The change affects</div><div class="line"><a name="l02720"></a><span class="lineno"> 2720</span>&#160;members `char* f` and `char* l` (see below).</div><div class="line"><a name="l02721"></a><span class="lineno"> 2721</span>&#160;</div><div class="line"><a name="l02722"></a><span class="lineno"> 2722</span>&#160;A record class (can be a struct in C) with fixed values for attributes and</div><div class="line"><a name="l02723"></a><span class="lineno"> 2723</span>&#160;elements is declared as follows:</div><div class="line"><a name="l02724"></a><span class="lineno"> 2724</span>&#160;</div><div class="line"><a name="l02725"></a><span class="lineno"> 2725</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02726"></a><span class="lineno"> 2726</span>&#160;    class ns__record_with_fixed</div><div class="line"><a name="l02727"></a><span class="lineno"> 2727</span>&#160;    {</div><div class="line"><a name="l02728"></a><span class="lineno"> 2728</span>&#160;     public:</div><div class="line"><a name="l02729"></a><span class="lineno"> 2729</span>&#160;      @ std::string  g   == &quot;G&quot;; // optional XML attribute with fixed value &quot;G&quot;</div><div class="line"><a name="l02730"></a><span class="lineno"> 2730</span>&#160;      @ std::string  h 1 == &quot;H&quot;; // required XML attribute with fixed value &quot;H&quot;</div><div class="line"><a name="l02731"></a><span class="lineno"> 2731</span>&#160;      @ std::string *i   == &quot;I&quot;; // optional XML attribute with fixed value &quot;I&quot;</div><div class="line"><a name="l02732"></a><span class="lineno"> 2732</span>&#160;        std::string  j 0 == &quot;J&quot;; // optional XML element with fixed value &quot;J&quot;</div><div class="line"><a name="l02733"></a><span class="lineno"> 2733</span>&#160;        std::string  k   == &quot;K&quot;; // required XML element with fixed value &quot;K&quot;</div><div class="line"><a name="l02734"></a><span class="lineno"> 2734</span>&#160;        std::string *l   == &quot;L&quot;; // optional XML element with fixed value &quot;L&quot;</div><div class="line"><a name="l02735"></a><span class="lineno"> 2735</span>&#160;        ...</div><div class="line"><a name="l02736"></a><span class="lineno"> 2736</span>&#160;    };</div><div class="line"><a name="l02737"></a><span class="lineno"> 2737</span>&#160;~~~</div><div class="line"><a name="l02738"></a><span class="lineno"> 2738</span>&#160;</div><div class="line"><a name="l02739"></a><span class="lineno"> 2739</span>&#160;With C `char*` (or `const char*`, `const wchar_t*`) strings in a struct, this</div><div class="line"><a name="l02740"></a><span class="lineno"> 2740</span>&#160;becomes:</div><div class="line"><a name="l02741"></a><span class="lineno"> 2741</span>&#160;</div><div class="line"><a name="l02742"></a><span class="lineno"> 2742</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02743"></a><span class="lineno"> 2743</span>&#160;    struct ns__record_with_fixed</div><div class="line"><a name="l02744"></a><span class="lineno"> 2744</span>&#160;    {</div><div class="line"><a name="l02745"></a><span class="lineno"> 2745</span>&#160;      @ char* g   == &quot;G&quot;; // optional XML attribute with fixed value &quot;G&quot;</div><div class="line"><a name="l02746"></a><span class="lineno"> 2746</span>&#160;      @ char* h 1 == &quot;H&quot;; // required XML attribute with fixed value &quot;H&quot;</div><div class="line"><a name="l02747"></a><span class="lineno"> 2747</span>&#160;        char* k 1 == &quot;K&quot;; // required XML element with fixed value &quot;K&quot;</div><div class="line"><a name="l02748"></a><span class="lineno"> 2748</span>&#160;        char* l   == &quot;L&quot;; // optional XML element with fixed value &quot;L&quot;</div><div class="line"><a name="l02749"></a><span class="lineno"> 2749</span>&#160;        ...</div><div class="line"><a name="l02750"></a><span class="lineno"> 2750</span>&#160;    };</div><div class="line"><a name="l02751"></a><span class="lineno"> 2751</span>&#160;~~~</div><div class="line"><a name="l02752"></a><span class="lineno"> 2752</span>&#160;</div><div class="line"><a name="l02753"></a><span class="lineno"> 2753</span>&#160;The XML schema validation rules for the examples above are as follows:</div><div class="line"><a name="l02754"></a><span class="lineno"> 2754</span>&#160;</div><div class="line"><a name="l02755"></a><span class="lineno"> 2755</span>&#160;Member | Notes</div><div class="line"><a name="l02756"></a><span class="lineno"> 2756</span>&#160;------ | ---------------------------------------------------------------------</div><div class="line"><a name="l02757"></a><span class="lineno"> 2757</span>&#160;`a`    | attribute may appear once; if it does not appear its value is &quot;A&quot;, otherwise its value is that given (also note: instantiating `ns__record_with_default` assigns the default value &quot;A&quot;)</div><div class="line"><a name="l02758"></a><span class="lineno"> 2758</span>&#160;`b`    | has no effect when parsing XML (but note: instantiating `ns__record_with_default` assigns the default value &quot;B&quot;)</div><div class="line"><a name="l02759"></a><span class="lineno"> 2759</span>&#160;`c`    | attribute may appear once; if it does not appear its value is &quot;C&quot;, otherwise its value is that given (also note: instantiating `ns__record_with_default` assigns NULL)</div><div class="line"><a name="l02760"></a><span class="lineno"> 2760</span>&#160;`d`    | element may appear once; if it does not appear or if it is empty, its value is &quot;D&quot;; otherwise its value is that given (also note: instantiating `ns__record_with_default` assigns the default value &quot;D&quot;)</div><div class="line"><a name="l02761"></a><span class="lineno"> 2761</span>&#160;`e`    | has no effect when parsing XML (but note: instantiating `ns__record_with_default` assigns the default value &quot;E&quot;)</div><div class="line"><a name="l02762"></a><span class="lineno"> 2762</span>&#160;`f`    | element may appear once; if it does not appear it is not provided; if it does appear and it is empty, its value is &quot;F&quot;; otherwise its value is that given (also note: instantiating `ns__record_with_default` assigns NULL)</div><div class="line"><a name="l02763"></a><span class="lineno"> 2763</span>&#160;`g`    | attribute may appear once; if it does not appear its value is &quot;G&quot;, if it does not appear its value is &quot;G&quot; (also note: instantiating `ns__record_with_fixed` assigns the fixed value &quot;G&quot;)</div><div class="line"><a name="l02764"></a><span class="lineno"> 2764</span>&#160;`h`    | attribute must appear once, its value must be &quot;H&quot; (also note: instantiating `ns__record_with_fixed` assigns the fixed value &quot;H&quot;)</div><div class="line"><a name="l02765"></a><span class="lineno"> 2765</span>&#160;`i`    | attribute may appear once; if it does not appear its value is &quot;I&quot;, if it does not appear its value is &quot;I&quot; (also note: instantiating `ns__record_with_fixed` assigns NULL)</div><div class="line"><a name="l02766"></a><span class="lineno"> 2766</span>&#160;`j`    | element may appear once, if it does not appear it is not provided; if it does appear and it is empty, its value is &quot;J&quot;; if it does appear and it is not empty, its value must be &quot;J&quot; (also note: instantiating `ns__record_with_fixed` assigns the fixed value &quot;J&quot;)</div><div class="line"><a name="l02767"></a><span class="lineno"> 2767</span>&#160;`k`    | element must appear once, its value must be &quot;K&quot; (also note: instantiating `ns__record_with_fixed` assigns the fixed value &quot;K&quot;)</div><div class="line"><a name="l02768"></a><span class="lineno"> 2768</span>&#160;`l`    | element may appear once, if it does not appear it is not provided; if it does appear and it is empty, its value is &quot;J&quot;; if it does appear and it is not empty, its value must be &quot;J&quot; (also note: instantiating `ns__record_with_fixed` assigns NULL)</div><div class="line"><a name="l02769"></a><span class="lineno"> 2769</span>&#160;</div><div class="line"><a name="l02770"></a><span class="lineno"> 2770</span>&#160;Members of type `char[N]` (fixed length string) can have default and fixed</div><div class="line"><a name="l02771"></a><span class="lineno"> 2771</span>&#160;values, when &lt;b&gt;`soapcpp2 -b`&lt;/b&gt; option &lt;b&gt;`-b`&lt;/b&gt; is used.  Also `char**`</div><div class="line"><a name="l02772"></a><span class="lineno"> 2772</span>&#160;(pointer to a string) members can have default and fixed values.  However,</div><div class="line"><a name="l02773"></a><span class="lineno"> 2773</span>&#160;members of this type will be initialized to NULL.  The default/fixed values</div><div class="line"><a name="l02774"></a><span class="lineno"> 2774</span>&#160;will be assigned with the same rules as for `char*` when deserialized from XML.</div><div class="line"><a name="l02775"></a><span class="lineno"> 2775</span>&#160;</div><div class="line"><a name="l02776"></a><span class="lineno"> 2776</span>&#160;@see Section [operations on classes and structs](#toxsd9-14).</div><div class="line"><a name="l02777"></a><span class="lineno"> 2777</span>&#160;</div><div class="line"><a name="l02778"></a><span class="lineno"> 2778</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l02779"></a><span class="lineno"> 2779</span>&#160;</div><div class="line"><a name="l02780"></a><span class="lineno"> 2780</span>&#160;### Attribute members                                                {#toxsd9-5}</div><div class="line"><a name="l02781"></a><span class="lineno"> 2781</span>&#160;</div><div class="line"><a name="l02782"></a><span class="lineno"> 2782</span>&#160;Class and struct data members are declared as XML attributes by annotating</div><div class="line"><a name="l02783"></a><span class="lineno"> 2783</span>&#160;their type with a `@` qualifier:</div><div class="line"><a name="l02784"></a><span class="lineno"> 2784</span>&#160;</div><div class="line"><a name="l02785"></a><span class="lineno"> 2785</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02786"></a><span class="lineno"> 2786</span>&#160;    class ns__record</div><div class="line"><a name="l02787"></a><span class="lineno"> 2787</span>&#160;    {</div><div class="line"><a name="l02788"></a><span class="lineno"> 2788</span>&#160;     public:</div><div class="line"><a name="l02789"></a><span class="lineno"> 2789</span>&#160;      @ std::string name;    // required (non-pointer means required)</div><div class="line"><a name="l02790"></a><span class="lineno"> 2790</span>&#160;      @ uint64_t    SSN;     // required (non-pointer means required)</div><div class="line"><a name="l02791"></a><span class="lineno"> 2791</span>&#160;        ns__record  *spouse; // optional (pointer means minOccurs=0)</div><div class="line"><a name="l02792"></a><span class="lineno"> 2792</span>&#160;    };</div><div class="line"><a name="l02793"></a><span class="lineno"> 2793</span>&#160;~~~</div><div class="line"><a name="l02794"></a><span class="lineno"> 2794</span>&#160;</div><div class="line"><a name="l02795"></a><span class="lineno"> 2795</span>&#160;This class maps to a complexType in the soapcpp2-generated XML schema:</div><div class="line"><a name="l02796"></a><span class="lineno"> 2796</span>&#160;</div><div class="line"><a name="l02797"></a><span class="lineno"> 2797</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l02798"></a><span class="lineno"> 2798</span>&#160;~~~{.xml}</div><div class="line"><a name="l02799"></a><span class="lineno"> 2799</span>&#160;    &lt;complexType name=&quot;record&quot;&gt;</div><div class="line"><a name="l02800"></a><span class="lineno"> 2800</span>&#160;      &lt;sequence&gt;</div><div class="line"><a name="l02801"></a><span class="lineno"> 2801</span>&#160;        &lt;element name=&quot;spouse&quot; type=&quot;ns:record&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot; nillable=&quot;true&quot;/&gt;</div><div class="line"><a name="l02802"></a><span class="lineno"> 2802</span>&#160;      &lt;/sequence&gt;</div><div class="line"><a name="l02803"></a><span class="lineno"> 2803</span>&#160;      &lt;attribute name=&quot;name&quot; type=&quot;xsd:string&quot; use=&quot;required&quot;/&gt;</div><div class="line"><a name="l02804"></a><span class="lineno"> 2804</span>&#160;      &lt;attribute name=&quot;SSN&quot; type=&quot;xsd:unsignedLong&quot; use=&quot;required&quot;/&gt;</div><div class="line"><a name="l02805"></a><span class="lineno"> 2805</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l02806"></a><span class="lineno"> 2806</span>&#160;~~~</div><div class="line"><a name="l02807"></a><span class="lineno"> 2807</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l02808"></a><span class="lineno"> 2808</span>&#160;</div><div class="line"><a name="l02809"></a><span class="lineno"> 2809</span>&#160;An example XML instance of `ns__record` is:</div><div class="line"><a name="l02810"></a><span class="lineno"> 2810</span>&#160;</div><div class="line"><a name="l02811"></a><span class="lineno"> 2811</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l02812"></a><span class="lineno"> 2812</span>&#160;~~~{.xml}</div><div class="line"><a name="l02813"></a><span class="lineno"> 2813</span>&#160;    &lt;ns:record xmlns:ns=&quot;urn:types&quot; name=&quot;Joe&quot; SSN=&quot;1234567890&quot;&gt;</div><div class="line"><a name="l02814"></a><span class="lineno"> 2814</span>&#160;      &lt;spouse name=&quot;Jane&quot; SSN=&quot;1987654320&quot;&gt;</div><div class="line"><a name="l02815"></a><span class="lineno"> 2815</span>&#160;      &lt;/spouse&gt;</div><div class="line"><a name="l02816"></a><span class="lineno"> 2816</span>&#160;    &lt;/ns:record&gt;</div><div class="line"><a name="l02817"></a><span class="lineno"> 2817</span>&#160;~~~</div><div class="line"><a name="l02818"></a><span class="lineno"> 2818</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l02819"></a><span class="lineno"> 2819</span>&#160;</div><div class="line"><a name="l02820"></a><span class="lineno"> 2820</span>&#160;Attribute data members are restricted to primitive types (`bool`, `enum`,</div><div class="line"><a name="l02821"></a><span class="lineno"> 2821</span>&#160;`time_t`, numeric and string types), `xsd__hexBinary`, `xsd__base64Binary`, and</div><div class="line"><a name="l02822"></a><span class="lineno"> 2822</span>&#160;custom serializers, such as `xsd__dateTime`.  Custom serializers for types that</div><div class="line"><a name="l02823"></a><span class="lineno"> 2823</span>&#160;may be used as attributes should define `soap_s2T` and `soap_T2s` functions that</div><div class="line"><a name="l02824"></a><span class="lineno"> 2824</span>&#160;convert values of type `T` to strings and back.</div><div class="line"><a name="l02825"></a><span class="lineno"> 2825</span>&#160;</div><div class="line"><a name="l02826"></a><span class="lineno"> 2826</span>&#160;Attribute data members can be pointers and smart pointers to these types, which</div><div class="line"><a name="l02827"></a><span class="lineno"> 2827</span>&#160;permits attributes to be optional.</div><div class="line"><a name="l02828"></a><span class="lineno"> 2828</span>&#160;</div><div class="line"><a name="l02829"></a><span class="lineno"> 2829</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l02830"></a><span class="lineno"> 2830</span>&#160;</div><div class="line"><a name="l02831"></a><span class="lineno"> 2831</span>&#160;### Backtick XML tags                                                {#toxsd9-5-1}</div><div class="line"><a name="l02832"></a><span class="lineno"> 2832</span>&#160;</div><div class="line"><a name="l02833"></a><span class="lineno"> 2833</span>&#160;The XML tag name of a class/struct member is the name of the member with the</div><div class="line"><a name="l02834"></a><span class="lineno"> 2834</span>&#160;usual XML tag translation, see [colon notation](#toxsd2).</div><div class="line"><a name="l02835"></a><span class="lineno"> 2835</span>&#160;</div><div class="line"><a name="l02836"></a><span class="lineno"> 2836</span>&#160;To override the standard translation of identifier names to XML tag names of</div><div class="line"><a name="l02837"></a><span class="lineno"> 2837</span>&#160;attributes and elements, add the XML tag name in backticks (requires gSOAP</div><div class="line"><a name="l02838"></a><span class="lineno"> 2838</span>&#160;2.8.30 or greater):</div><div class="line"><a name="l02839"></a><span class="lineno"> 2839</span>&#160;</div><div class="line"><a name="l02840"></a><span class="lineno"> 2840</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02841"></a><span class="lineno"> 2841</span>&#160;    class ns__record</div><div class="line"><a name="l02842"></a><span class="lineno"> 2842</span>&#160;    {</div><div class="line"><a name="l02843"></a><span class="lineno"> 2843</span>&#160;     public:</div><div class="line"><a name="l02844"></a><span class="lineno"> 2844</span>&#160;      @ std::string name    `full-name`;</div><div class="line"><a name="l02845"></a><span class="lineno"> 2845</span>&#160;      @ uint64_t    SSN     `tax-id`;</div><div class="line"><a name="l02846"></a><span class="lineno"> 2846</span>&#160;        ns__record *spouse  `married-to`;</div><div class="line"><a name="l02847"></a><span class="lineno"> 2847</span>&#160;    };</div><div class="line"><a name="l02848"></a><span class="lineno"> 2848</span>&#160;~~~</div><div class="line"><a name="l02849"></a><span class="lineno"> 2849</span>&#160;</div><div class="line"><a name="l02850"></a><span class="lineno"> 2850</span>&#160;This class maps to a complexType in the soapcpp2-generated XML schema:</div><div class="line"><a name="l02851"></a><span class="lineno"> 2851</span>&#160;</div><div class="line"><a name="l02852"></a><span class="lineno"> 2852</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l02853"></a><span class="lineno"> 2853</span>&#160;~~~{.xml}</div><div class="line"><a name="l02854"></a><span class="lineno"> 2854</span>&#160;    &lt;complexType name=&quot;record&quot;&gt;</div><div class="line"><a name="l02855"></a><span class="lineno"> 2855</span>&#160;      &lt;sequence&gt;</div><div class="line"><a name="l02856"></a><span class="lineno"> 2856</span>&#160;        &lt;element name=&quot;married-to&quot; type=&quot;ns:record&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l02857"></a><span class="lineno"> 2857</span>&#160;      &lt;/sequence&gt;</div><div class="line"><a name="l02858"></a><span class="lineno"> 2858</span>&#160;      &lt;attribute name=&quot;full-name&quot; type=&quot;xsd:string&quot; use=&quot;required&quot;/&gt;</div><div class="line"><a name="l02859"></a><span class="lineno"> 2859</span>&#160;      &lt;attribute name=&quot;tax-id&quot; type=&quot;xsd:unsignedLong&quot; use=&quot;required&quot;/&gt;</div><div class="line"><a name="l02860"></a><span class="lineno"> 2860</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l02861"></a><span class="lineno"> 2861</span>&#160;~~~</div><div class="line"><a name="l02862"></a><span class="lineno"> 2862</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l02863"></a><span class="lineno"> 2863</span>&#160;</div><div class="line"><a name="l02864"></a><span class="lineno"> 2864</span>&#160;An example XML instance of `ns__record` is:</div><div class="line"><a name="l02865"></a><span class="lineno"> 2865</span>&#160;</div><div class="line"><a name="l02866"></a><span class="lineno"> 2866</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l02867"></a><span class="lineno"> 2867</span>&#160;~~~{.xml}</div><div class="line"><a name="l02868"></a><span class="lineno"> 2868</span>&#160;    &lt;ns:record xmlns:ns=&quot;urn:types&quot; full-name=&quot;Joe&quot; tax-id=&quot;1234567890&quot;&gt;</div><div class="line"><a name="l02869"></a><span class="lineno"> 2869</span>&#160;      &lt;married-to full-name=&quot;Jane&quot; tax-id=&quot;1987654320&quot;&gt;</div><div class="line"><a name="l02870"></a><span class="lineno"> 2870</span>&#160;      &lt;/married-to&gt;</div><div class="line"><a name="l02871"></a><span class="lineno"> 2871</span>&#160;    &lt;/ns:record&gt;</div><div class="line"><a name="l02872"></a><span class="lineno"> 2872</span>&#160;~~~</div><div class="line"><a name="l02873"></a><span class="lineno"> 2873</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l02874"></a><span class="lineno"> 2874</span>&#160;</div><div class="line"><a name="l02875"></a><span class="lineno"> 2875</span>&#160;A backtick XML tag name may contain any non-empty sequence of ASCII and UTF-8</div><div class="line"><a name="l02876"></a><span class="lineno"> 2876</span>&#160;characters except white space and the backtick character.  A backtick tag can</div><div class="line"><a name="l02877"></a><span class="lineno"> 2877</span>&#160;be combined with member constraints and default member initializers:</div><div class="line"><a name="l02878"></a><span class="lineno"> 2878</span>&#160;</div><div class="line"><a name="l02879"></a><span class="lineno"> 2879</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02880"></a><span class="lineno"> 2880</span>&#160;    @ uint64_t SSN `tax-id` 0:1 = 999;</div><div class="line"><a name="l02881"></a><span class="lineno"> 2881</span>&#160;~~~</div><div class="line"><a name="l02882"></a><span class="lineno"> 2882</span>&#160;</div><div class="line"><a name="l02883"></a><span class="lineno"> 2883</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l02884"></a><span class="lineno"> 2884</span>&#160;</div><div class="line"><a name="l02885"></a><span class="lineno"> 2885</span>&#160;### Qualified and unqualified members                                {#toxsd9-6}</div><div class="line"><a name="l02886"></a><span class="lineno"> 2886</span>&#160;</div><div class="line"><a name="l02887"></a><span class="lineno"> 2887</span>&#160;Class, struct, and union data members are mapped to namespace qualified or</div><div class="line"><a name="l02888"></a><span class="lineno"> 2888</span>&#160;unqualified tag names of local elements and attributes.  If a data member has</div><div class="line"><a name="l02889"></a><span class="lineno"> 2889</span>&#160;no prefix then the default form of qualification is applied based on the</div><div class="line"><a name="l02890"></a><span class="lineno"> 2890</span>&#160;element/attribute form that is declared with the XML schema of the class, struct,</div><div class="line"><a name="l02891"></a><span class="lineno"> 2891</span>&#160;or union type.  If the member name has a namespace prefix by colon notation,</div><div class="line"><a name="l02892"></a><span class="lineno"> 2892</span>&#160;then the prefix overrules the default (un)qualified form.  Therefore,</div><div class="line"><a name="l02893"></a><span class="lineno"> 2893</span>&#160;[colon notation](#toxsd2) is an effective mechanism to control qualification of</div><div class="line"><a name="l02894"></a><span class="lineno"> 2894</span>&#160;tag names of individual members of classes, structs, and unions.</div><div class="line"><a name="l02895"></a><span class="lineno"> 2895</span>&#160;</div><div class="line"><a name="l02896"></a><span class="lineno"> 2896</span>&#160;The XML schema elementFormDefault and attributeFormDefault declarations control</div><div class="line"><a name="l02897"></a><span class="lineno"> 2897</span>&#160;the tag name qualification of local elements and attributes, respectively.</div><div class="line"><a name="l02898"></a><span class="lineno"> 2898</span>&#160;</div><div class="line"><a name="l02899"></a><span class="lineno"> 2899</span>&#160;- &quot;unqualified&quot; indicates that local elements/attributes are not qualified with</div><div class="line"><a name="l02900"></a><span class="lineno"> 2900</span>&#160;  the namespace prefix.</div><div class="line"><a name="l02901"></a><span class="lineno"> 2901</span>&#160;</div><div class="line"><a name="l02902"></a><span class="lineno"> 2902</span>&#160;- &quot;qualified&quot; indicates that local elements/attributes must be qualified with</div><div class="line"><a name="l02903"></a><span class="lineno"> 2903</span>&#160;  the namespace prefix.</div><div class="line"><a name="l02904"></a><span class="lineno"> 2904</span>&#160;</div><div class="line"><a name="l02905"></a><span class="lineno"> 2905</span>&#160;Individual schema declarations of local elements and attributes may overrule</div><div class="line"><a name="l02906"></a><span class="lineno"> 2906</span>&#160;this by using the form declaration in an XML schema and by using colon notation</div><div class="line"><a name="l02907"></a><span class="lineno"> 2907</span>&#160;to add namespace prefixes to class, struct, and union members in the header</div><div class="line"><a name="l02908"></a><span class="lineno"> 2908</span>&#160;file for soapcpp2.</div><div class="line"><a name="l02909"></a><span class="lineno"> 2909</span>&#160;</div><div class="line"><a name="l02910"></a><span class="lineno"> 2910</span>&#160;Consider for example an `ns__record` class in the `ns` namespace in which local</div><div class="line"><a name="l02911"></a><span class="lineno"> 2911</span>&#160;elements are qualified and local attributes are unqualified by default:</div><div class="line"><a name="l02912"></a><span class="lineno"> 2912</span>&#160;</div><div class="line"><a name="l02913"></a><span class="lineno"> 2913</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02914"></a><span class="lineno"> 2914</span>&#160;    //gsoap ns schema namespace:     urn:types</div><div class="line"><a name="l02915"></a><span class="lineno"> 2915</span>&#160;    //gsoap ns schema elementForm:   qualified</div><div class="line"><a name="l02916"></a><span class="lineno"> 2916</span>&#160;    //gsoap ns schema attributeForm: unqualified</div><div class="line"><a name="l02917"></a><span class="lineno"> 2917</span>&#160;    class ns__record</div><div class="line"><a name="l02918"></a><span class="lineno"> 2918</span>&#160;    {</div><div class="line"><a name="l02919"></a><span class="lineno"> 2919</span>&#160;     public:</div><div class="line"><a name="l02920"></a><span class="lineno"> 2920</span>&#160;      @ std::string name;</div><div class="line"><a name="l02921"></a><span class="lineno"> 2921</span>&#160;      @ uint64_t    SSN;</div><div class="line"><a name="l02922"></a><span class="lineno"> 2922</span>&#160;        ns__record *spouse;</div><div class="line"><a name="l02923"></a><span class="lineno"> 2923</span>&#160;    };</div><div class="line"><a name="l02924"></a><span class="lineno"> 2924</span>&#160;~~~</div><div class="line"><a name="l02925"></a><span class="lineno"> 2925</span>&#160;</div><div class="line"><a name="l02926"></a><span class="lineno"> 2926</span>&#160;This class maps to a complexType in the soapcpp2-generated XML schema with</div><div class="line"><a name="l02927"></a><span class="lineno"> 2927</span>&#160;targetNamespace &quot;urn:types&quot;, elementFormDefault qualified and</div><div class="line"><a name="l02928"></a><span class="lineno"> 2928</span>&#160;attributeFormDefault unqualified:</div><div class="line"><a name="l02929"></a><span class="lineno"> 2929</span>&#160;</div><div class="line"><a name="l02930"></a><span class="lineno"> 2930</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l02931"></a><span class="lineno"> 2931</span>&#160;~~~{.xml}</div><div class="line"><a name="l02932"></a><span class="lineno"> 2932</span>&#160;    &lt;schema targetNamespace=&quot;urn:types&quot;</div><div class="line"><a name="l02933"></a><span class="lineno"> 2933</span>&#160;      ...</div><div class="line"><a name="l02934"></a><span class="lineno"> 2934</span>&#160;      elementFormDefault=&quot;qualified&quot;</div><div class="line"><a name="l02935"></a><span class="lineno"> 2935</span>&#160;      attributeFormDefault=&quot;unqualified&quot;</div><div class="line"><a name="l02936"></a><span class="lineno"> 2936</span>&#160;      ...  &gt;</div><div class="line"><a name="l02937"></a><span class="lineno"> 2937</span>&#160;      &lt;complexType name=&quot;record&quot;&gt;</div><div class="line"><a name="l02938"></a><span class="lineno"> 2938</span>&#160;        &lt;sequence&gt;</div><div class="line"><a name="l02939"></a><span class="lineno"> 2939</span>&#160;          &lt;element name=&quot;spouse&quot; type=&quot;ns:record&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l02940"></a><span class="lineno"> 2940</span>&#160;        &lt;/sequence&gt;</div><div class="line"><a name="l02941"></a><span class="lineno"> 2941</span>&#160;        &lt;attribute name=&quot;name&quot; type=&quot;xsd:string&quot; use=&quot;required&quot;/&gt;</div><div class="line"><a name="l02942"></a><span class="lineno"> 2942</span>&#160;        &lt;attribute name=&quot;SSN&quot; type=&quot;xsd:unsignedLong&quot; use=&quot;required&quot;/&gt;</div><div class="line"><a name="l02943"></a><span class="lineno"> 2943</span>&#160;      &lt;/complexType&gt;</div><div class="line"><a name="l02944"></a><span class="lineno"> 2944</span>&#160;    &lt;/schema&gt;</div><div class="line"><a name="l02945"></a><span class="lineno"> 2945</span>&#160;~~~</div><div class="line"><a name="l02946"></a><span class="lineno"> 2946</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l02947"></a><span class="lineno"> 2947</span>&#160;</div><div class="line"><a name="l02948"></a><span class="lineno"> 2948</span>&#160;An example XML instance of `ns__record` is:</div><div class="line"><a name="l02949"></a><span class="lineno"> 2949</span>&#160;</div><div class="line"><a name="l02950"></a><span class="lineno"> 2950</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l02951"></a><span class="lineno"> 2951</span>&#160;~~~{.xml}</div><div class="line"><a name="l02952"></a><span class="lineno"> 2952</span>&#160;    &lt;ns:record xmlns:ns=&quot;urn:types&quot; name=&quot;Joe&quot; SSN=&quot;1234567890&quot;&gt;</div><div class="line"><a name="l02953"></a><span class="lineno"> 2953</span>&#160;      &lt;ns:spouse&gt; name=&quot;Jane&quot; SSN=&quot;1987654320&quot;&gt;</div><div class="line"><a name="l02954"></a><span class="lineno"> 2954</span>&#160;      &lt;/ns:spouse&gt;</div><div class="line"><a name="l02955"></a><span class="lineno"> 2955</span>&#160;    &lt;/ns:record&gt;</div><div class="line"><a name="l02956"></a><span class="lineno"> 2956</span>&#160;~~~</div><div class="line"><a name="l02957"></a><span class="lineno"> 2957</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l02958"></a><span class="lineno"> 2958</span>&#160;</div><div class="line"><a name="l02959"></a><span class="lineno"> 2959</span>&#160;Here the root element &lt;i&gt;`&lt;ns:record&gt;`&lt;/i&gt; is qualified because it is a root</div><div class="line"><a name="l02960"></a><span class="lineno"> 2960</span>&#160;element of the XML schema with target namespace &quot;urn:types&quot;.  Its local element</div><div class="line"><a name="l02961"></a><span class="lineno"> 2961</span>&#160;&lt;i&gt;`&lt;ns:spouse&gt;`&lt;/i&gt; is namespace qualified because the elementFormDefault of</div><div class="line"><a name="l02962"></a><span class="lineno"> 2962</span>&#160;local elements is qualified.  Attributes are unqualified.</div><div class="line"><a name="l02963"></a><span class="lineno"> 2963</span>&#160;</div><div class="line"><a name="l02964"></a><span class="lineno"> 2964</span>&#160;The default namespace (un)qualification of local elements and attributes can be</div><div class="line"><a name="l02965"></a><span class="lineno"> 2965</span>&#160;overruled by adding a prefix to the member name by using colon notation:</div><div class="line"><a name="l02966"></a><span class="lineno"> 2966</span>&#160;</div><div class="line"><a name="l02967"></a><span class="lineno"> 2967</span>&#160;~~~{.cpp}</div><div class="line"><a name="l02968"></a><span class="lineno"> 2968</span>&#160;    //gsoap ns schema namespace:     urn:types</div><div class="line"><a name="l02969"></a><span class="lineno"> 2969</span>&#160;    //gsoap ns schema elementForm:   qualified</div><div class="line"><a name="l02970"></a><span class="lineno"> 2970</span>&#160;    //gsoap ns schema attributeForm: unqualified</div><div class="line"><a name="l02971"></a><span class="lineno"> 2971</span>&#160;    class ns__record</div><div class="line"><a name="l02972"></a><span class="lineno"> 2972</span>&#160;    {</div><div class="line"><a name="l02973"></a><span class="lineno"> 2973</span>&#160;     public:</div><div class="line"><a name="l02974"></a><span class="lineno"> 2974</span>&#160;      @ std::string ns:name; // &#39;ns:&#39; qualified</div><div class="line"><a name="l02975"></a><span class="lineno"> 2975</span>&#160;      @ uint64_t    SSN;</div><div class="line"><a name="l02976"></a><span class="lineno"> 2976</span>&#160;        ns__record *:spouse; // &#39;:&#39; unqualified (empty prefix)</div><div class="line"><a name="l02977"></a><span class="lineno"> 2977</span>&#160;    };</div><div class="line"><a name="l02978"></a><span class="lineno"> 2978</span>&#160;~~~</div><div class="line"><a name="l02979"></a><span class="lineno"> 2979</span>&#160;</div><div class="line"><a name="l02980"></a><span class="lineno"> 2980</span>&#160;The colon notation for member &lt;i&gt;`ns:name`&lt;/i&gt; forces qualification of its attribute</div><div class="line"><a name="l02981"></a><span class="lineno"> 2981</span>&#160;tag in XML.  The colon notation for member &lt;i&gt;`:spouse`&lt;/i&gt; removes qualification from</div><div class="line"><a name="l02982"></a><span class="lineno"> 2982</span>&#160;its local element tag:</div><div class="line"><a name="l02983"></a><span class="lineno"> 2983</span>&#160;</div><div class="line"><a name="l02984"></a><span class="lineno"> 2984</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l02985"></a><span class="lineno"> 2985</span>&#160;~~~{.xml}</div><div class="line"><a name="l02986"></a><span class="lineno"> 2986</span>&#160;    &lt;schema targetNamespace=&quot;urn:types&quot;</div><div class="line"><a name="l02987"></a><span class="lineno"> 2987</span>&#160;      ...</div><div class="line"><a name="l02988"></a><span class="lineno"> 2988</span>&#160;      elementFormDefault=&quot;unqualified&quot;</div><div class="line"><a name="l02989"></a><span class="lineno"> 2989</span>&#160;      attributeFormDefault=&quot;unqualified&quot;</div><div class="line"><a name="l02990"></a><span class="lineno"> 2990</span>&#160;      ... &gt;</div><div class="line"><a name="l02991"></a><span class="lineno"> 2991</span>&#160;      &lt;complexType name=&quot;record&quot;&gt;</div><div class="line"><a name="l02992"></a><span class="lineno"> 2992</span>&#160;        &lt;sequence&gt;</div><div class="line"><a name="l02993"></a><span class="lineno"> 2993</span>&#160;          &lt;element name=&quot;spouse&quot; type=&quot;ns:record&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot; form=&quot;unqualified&quot;/&gt;</div><div class="line"><a name="l02994"></a><span class="lineno"> 2994</span>&#160;        &lt;/sequence&gt;</div><div class="line"><a name="l02995"></a><span class="lineno"> 2995</span>&#160;        &lt;attribute name=&quot;name&quot; type=&quot;xsd:string&quot; use=&quot;required&quot; form=&quot;qualified&quot;/&gt;</div><div class="line"><a name="l02996"></a><span class="lineno"> 2996</span>&#160;        &lt;attribute name=&quot;SSN&quot; type=&quot;xsd:unsignedLong&quot; use=&quot;required&quot;/&gt;</div><div class="line"><a name="l02997"></a><span class="lineno"> 2997</span>&#160;      &lt;/complexType&gt;</div><div class="line"><a name="l02998"></a><span class="lineno"> 2998</span>&#160;    &lt;/schema&gt;</div><div class="line"><a name="l02999"></a><span class="lineno"> 2999</span>&#160;~~~</div><div class="line"><a name="l03000"></a><span class="lineno"> 3000</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03001"></a><span class="lineno"> 3001</span>&#160;</div><div class="line"><a name="l03002"></a><span class="lineno"> 3002</span>&#160;XML instances of `ns__record` have unqualified spouse elements and qualified</div><div class="line"><a name="l03003"></a><span class="lineno"> 3003</span>&#160;ns:name attributes:</div><div class="line"><a name="l03004"></a><span class="lineno"> 3004</span>&#160;</div><div class="line"><a name="l03005"></a><span class="lineno"> 3005</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03006"></a><span class="lineno"> 3006</span>&#160;~~~{.xml}</div><div class="line"><a name="l03007"></a><span class="lineno"> 3007</span>&#160;    &lt;ns:record xmlns:ns=&quot;urn:types&quot; ns:name=&quot;Joe&quot; SSN=&quot;1234567890&quot;&gt;</div><div class="line"><a name="l03008"></a><span class="lineno"> 3008</span>&#160;      &lt;spouse&gt; ns:name=&quot;Jane&quot; SSN=&quot;1987654320&quot;&gt;</div><div class="line"><a name="l03009"></a><span class="lineno"> 3009</span>&#160;      &lt;/spouse&gt;</div><div class="line"><a name="l03010"></a><span class="lineno"> 3010</span>&#160;    &lt;/ns:record&gt;</div><div class="line"><a name="l03011"></a><span class="lineno"> 3011</span>&#160;~~~</div><div class="line"><a name="l03012"></a><span class="lineno"> 3012</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03013"></a><span class="lineno"> 3013</span>&#160;</div><div class="line"><a name="l03014"></a><span class="lineno"> 3014</span>&#160;Members of a class or struct can also be prefixed using the `prefix__name`</div><div class="line"><a name="l03015"></a><span class="lineno"> 3015</span>&#160;convention or using colon notation `prefix:name`.  However, this has a</div><div class="line"><a name="l03016"></a><span class="lineno"> 3016</span>&#160;different effect by referring to global (root) elements and attributes, see</div><div class="line"><a name="l03017"></a><span class="lineno"> 3017</span>&#160;[document root element definitions](#toxsd9-7).</div><div class="line"><a name="l03018"></a><span class="lineno"> 3018</span>&#160;</div><div class="line"><a name="l03019"></a><span class="lineno"> 3019</span>&#160;[Backtick XML tags](#toxsd9-5-1) can be used in place of the member name</div><div class="line"><a name="l03020"></a><span class="lineno"> 3020</span>&#160;annotations and will achieve the same effect as described when these tag names</div><div class="line"><a name="l03021"></a><span class="lineno"> 3021</span>&#160;are (un)qualified (requires gSOAP 2.8.30 or greater).</div><div class="line"><a name="l03022"></a><span class="lineno"> 3022</span>&#160;</div><div class="line"><a name="l03023"></a><span class="lineno"> 3023</span>&#160;@note You must declare a target namespace with a `//gsoap ns schema namespace:`</div><div class="line"><a name="l03024"></a><span class="lineno"> 3024</span>&#160;directive to enable the `elementForm` and `attributeForm` directives in order</div><div class="line"><a name="l03025"></a><span class="lineno"> 3025</span>&#160;to generate valid XML schemas with soapcpp2.  See [directives](#directives) for</div><div class="line"><a name="l03026"></a><span class="lineno"> 3026</span>&#160;more details.</div><div class="line"><a name="l03027"></a><span class="lineno"> 3027</span>&#160;</div><div class="line"><a name="l03028"></a><span class="lineno"> 3028</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l03029"></a><span class="lineno"> 3029</span>&#160;</div><div class="line"><a name="l03030"></a><span class="lineno"> 3030</span>&#160;### Defining document root elements                                 {#toxsd9-7}</div><div class="line"><a name="l03031"></a><span class="lineno"> 3031</span>&#160;</div><div class="line"><a name="l03032"></a><span class="lineno"> 3032</span>&#160;To define and reference XML document root elements we use type names that start</div><div class="line"><a name="l03033"></a><span class="lineno"> 3033</span>&#160;with an underscore:</div><div class="line"><a name="l03034"></a><span class="lineno"> 3034</span>&#160;</div><div class="line"><a name="l03035"></a><span class="lineno"> 3035</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03036"></a><span class="lineno"> 3036</span>&#160;    class _ns__record</div><div class="line"><a name="l03037"></a><span class="lineno"> 3037</span>&#160;~~~</div><div class="line"><a name="l03038"></a><span class="lineno"> 3038</span>&#160;</div><div class="line"><a name="l03039"></a><span class="lineno"> 3039</span>&#160;Alternatively, we can use a `typedef` to define a document root element with a</div><div class="line"><a name="l03040"></a><span class="lineno"> 3040</span>&#160;given type:</div><div class="line"><a name="l03041"></a><span class="lineno"> 3041</span>&#160;</div><div class="line"><a name="l03042"></a><span class="lineno"> 3042</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03043"></a><span class="lineno"> 3043</span>&#160;    typedef ns__record _ns__record;</div><div class="line"><a name="l03044"></a><span class="lineno"> 3044</span>&#160;~~~</div><div class="line"><a name="l03045"></a><span class="lineno"> 3045</span>&#160;</div><div class="line"><a name="l03046"></a><span class="lineno"> 3046</span>&#160;This `typedef` maps to a global root element that is added to the</div><div class="line"><a name="l03047"></a><span class="lineno"> 3047</span>&#160;soapcpp2-generated XML schema:</div><div class="line"><a name="l03048"></a><span class="lineno"> 3048</span>&#160;</div><div class="line"><a name="l03049"></a><span class="lineno"> 3049</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03050"></a><span class="lineno"> 3050</span>&#160;~~~{.xml}</div><div class="line"><a name="l03051"></a><span class="lineno"> 3051</span>&#160;    &lt;element name=&quot;record&quot; type=&quot;ns:record&quot;/&gt;</div><div class="line"><a name="l03052"></a><span class="lineno"> 3052</span>&#160;~~~</div><div class="line"><a name="l03053"></a><span class="lineno"> 3053</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03054"></a><span class="lineno"> 3054</span>&#160;</div><div class="line"><a name="l03055"></a><span class="lineno"> 3055</span>&#160;An example XML instance of `_ns__record` is:</div><div class="line"><a name="l03056"></a><span class="lineno"> 3056</span>&#160;</div><div class="line"><a name="l03057"></a><span class="lineno"> 3057</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03058"></a><span class="lineno"> 3058</span>&#160;~~~{.xml}</div><div class="line"><a name="l03059"></a><span class="lineno"> 3059</span>&#160;    &lt;ns:record xmlns:ns=&quot;urn:types&quot;&gt;</div><div class="line"><a name="l03060"></a><span class="lineno"> 3060</span>&#160;      &lt;name&gt;Joe&lt;/name&gt;</div><div class="line"><a name="l03061"></a><span class="lineno"> 3061</span>&#160;      &lt;SSN&gt;1234567890&lt;/SSN&gt;</div><div class="line"><a name="l03062"></a><span class="lineno"> 3062</span>&#160;      &lt;spouse&gt;</div><div class="line"><a name="l03063"></a><span class="lineno"> 3063</span>&#160;        &lt;name&gt;Jane&lt;/name&gt;</div><div class="line"><a name="l03064"></a><span class="lineno"> 3064</span>&#160;        &lt;SSN&gt;1987654320&lt;/SSN&gt;</div><div class="line"><a name="l03065"></a><span class="lineno"> 3065</span>&#160;      &lt;/spouse&gt;</div><div class="line"><a name="l03066"></a><span class="lineno"> 3066</span>&#160;    &lt;/ns:record&gt;</div><div class="line"><a name="l03067"></a><span class="lineno"> 3067</span>&#160;~~~</div><div class="line"><a name="l03068"></a><span class="lineno"> 3068</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03069"></a><span class="lineno"> 3069</span>&#160;</div><div class="line"><a name="l03070"></a><span class="lineno"> 3070</span>&#160;Global-level element/attribute definitions are also referenced and/or added to</div><div class="line"><a name="l03071"></a><span class="lineno"> 3071</span>&#160;the generated XML schema when serializable data members reference these by</div><div class="line"><a name="l03072"></a><span class="lineno"> 3072</span>&#160;their qualified name:</div><div class="line"><a name="l03073"></a><span class="lineno"> 3073</span>&#160;</div><div class="line"><a name="l03074"></a><span class="lineno"> 3074</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03075"></a><span class="lineno"> 3075</span>&#160;    typedef std::string _ns__name 1 : 100;</div><div class="line"><a name="l03076"></a><span class="lineno"> 3076</span>&#160;    class _ns__record</div><div class="line"><a name="l03077"></a><span class="lineno"> 3077</span>&#160;    {</div><div class="line"><a name="l03078"></a><span class="lineno"> 3078</span>&#160;     public:</div><div class="line"><a name="l03079"></a><span class="lineno"> 3079</span>&#160;      @ _QName       xsi__type; // built-in XSD attribute xsi:type</div><div class="line"><a name="l03080"></a><span class="lineno"> 3080</span>&#160;        _ns__name    ns__name;  // ref to global ns:name element</div><div class="line"><a name="l03081"></a><span class="lineno"> 3081</span>&#160;        uint64_t     SSN;</div><div class="line"><a name="l03082"></a><span class="lineno"> 3082</span>&#160;        _ns__record *spouse;</div><div class="line"><a name="l03083"></a><span class="lineno"> 3083</span>&#160;    };</div><div class="line"><a name="l03084"></a><span class="lineno"> 3084</span>&#160;~~~</div><div class="line"><a name="l03085"></a><span class="lineno"> 3085</span>&#160;</div><div class="line"><a name="l03086"></a><span class="lineno"> 3086</span>&#160;These types map to the following comonents in the soapcpp2-generated XML</div><div class="line"><a name="l03087"></a><span class="lineno"> 3087</span>&#160;schema:</div><div class="line"><a name="l03088"></a><span class="lineno"> 3088</span>&#160;</div><div class="line"><a name="l03089"></a><span class="lineno"> 3089</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03090"></a><span class="lineno"> 3090</span>&#160;~~~{.xml}</div><div class="line"><a name="l03091"></a><span class="lineno"> 3091</span>&#160;    &lt;simpleType name=&quot;name&quot;&gt;</div><div class="line"><a name="l03092"></a><span class="lineno"> 3092</span>&#160;      &lt;restriction base=&quot;xsd:string&quot;&gt;</div><div class="line"><a name="l03093"></a><span class="lineno"> 3093</span>&#160;        &lt;minLength value=&quot;1&quot;/&gt;</div><div class="line"><a name="l03094"></a><span class="lineno"> 3094</span>&#160;        &lt;maxLength value=&quot;100&quot;/&gt;</div><div class="line"><a name="l03095"></a><span class="lineno"> 3095</span>&#160;      &lt;/restriction&gt;</div><div class="line"><a name="l03096"></a><span class="lineno"> 3096</span>&#160;    &lt;/simpleType&gt;</div><div class="line"><a name="l03097"></a><span class="lineno"> 3097</span>&#160;    &lt;element name=&quot;name&quot; type=&quot;ns:name&quot;/&gt;</div><div class="line"><a name="l03098"></a><span class="lineno"> 3098</span>&#160;    &lt;complexType name=&quot;record&quot;&gt;</div><div class="line"><a name="l03099"></a><span class="lineno"> 3099</span>&#160;      &lt;sequence&gt;</div><div class="line"><a name="l03100"></a><span class="lineno"> 3100</span>&#160;        &lt;element ref=&quot;ns:name&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03101"></a><span class="lineno"> 3101</span>&#160;        &lt;element name=&quot;SSN&quot; type=&quot;xsd:unsignedLong&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03102"></a><span class="lineno"> 3102</span>&#160;        &lt;element name=&quot;spouse&quot; type=&quot;ns:record&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03103"></a><span class="lineno"> 3103</span>&#160;      &lt;/sequence&gt;</div><div class="line"><a name="l03104"></a><span class="lineno"> 3104</span>&#160;      &lt;attribute ref=&quot;xsi:type&quot; use=&quot;optional&quot;/&gt;</div><div class="line"><a name="l03105"></a><span class="lineno"> 3105</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l03106"></a><span class="lineno"> 3106</span>&#160;    &lt;element name=&quot;record&quot; type=&quot;ns:record&quot;/&gt;</div><div class="line"><a name="l03107"></a><span class="lineno"> 3107</span>&#160;~~~</div><div class="line"><a name="l03108"></a><span class="lineno"> 3108</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03109"></a><span class="lineno"> 3109</span>&#160;</div><div class="line"><a name="l03110"></a><span class="lineno"> 3110</span>&#160;Use only use qualified member names when their types match the global-level</div><div class="line"><a name="l03111"></a><span class="lineno"> 3111</span>&#160;element types that they refer to.  For example:</div><div class="line"><a name="l03112"></a><span class="lineno"> 3112</span>&#160;</div><div class="line"><a name="l03113"></a><span class="lineno"> 3113</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03114"></a><span class="lineno"> 3114</span>&#160;    typedef std::string _ns__name; // global element ns:name of type xsd:string</div><div class="line"><a name="l03115"></a><span class="lineno"> 3115</span>&#160;    class _ns__record</div><div class="line"><a name="l03116"></a><span class="lineno"> 3116</span>&#160;    {</div><div class="line"><a name="l03117"></a><span class="lineno"> 3117</span>&#160;     public:</div><div class="line"><a name="l03118"></a><span class="lineno"> 3118</span>&#160;        int         ns__name;   // BAD: global element ns:name is NOT type int</div><div class="line"><a name="l03119"></a><span class="lineno"> 3119</span>&#160;        _ns__record ns__record; // OK: ns:record is a global-level root element</div><div class="line"><a name="l03120"></a><span class="lineno"> 3120</span>&#160;        ...</div><div class="line"><a name="l03121"></a><span class="lineno"> 3121</span>&#160;    };</div><div class="line"><a name="l03122"></a><span class="lineno"> 3122</span>&#160;~~~</div><div class="line"><a name="l03123"></a><span class="lineno"> 3123</span>&#160;</div><div class="line"><a name="l03124"></a><span class="lineno"> 3124</span>&#160;Therefore, we recommend to use qualified member names only when necessary to</div><div class="line"><a name="l03125"></a><span class="lineno"> 3125</span>&#160;refer to standard XSD elements and attributes, such as `xsi__type`, and</div><div class="line"><a name="l03126"></a><span class="lineno"> 3126</span>&#160;`xsd__lang`.</div><div class="line"><a name="l03127"></a><span class="lineno"> 3127</span>&#160;</div><div class="line"><a name="l03128"></a><span class="lineno"> 3128</span>&#160;By contrast, colon notation has the desired effect to (un)qualify local tag</div><div class="line"><a name="l03129"></a><span class="lineno"> 3129</span>&#160;names by overruling the default element/attribute namespace qualification, see</div><div class="line"><a name="l03130"></a><span class="lineno"> 3130</span>&#160;[qualified and unqualified members](#toxsd9-6).</div><div class="line"><a name="l03131"></a><span class="lineno"> 3131</span>&#160;</div><div class="line"><a name="l03132"></a><span class="lineno"> 3132</span>&#160;As an alternative to prefixing member names, use the backtick tag (requires</div><div class="line"><a name="l03133"></a><span class="lineno"> 3133</span>&#160;gSOAP 2.8.30 or greater):</div><div class="line"><a name="l03134"></a><span class="lineno"> 3134</span>&#160;</div><div class="line"><a name="l03135"></a><span class="lineno"> 3135</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03136"></a><span class="lineno"> 3136</span>&#160;    typedef std::string _ns__name 1 : 100;</div><div class="line"><a name="l03137"></a><span class="lineno"> 3137</span>&#160;    class _ns__record</div><div class="line"><a name="l03138"></a><span class="lineno"> 3138</span>&#160;    {</div><div class="line"><a name="l03139"></a><span class="lineno"> 3139</span>&#160;     public:</div><div class="line"><a name="l03140"></a><span class="lineno"> 3140</span>&#160;      @ _QName       t    &lt;i&gt;`xsi:type`&lt;/i&gt;; // built-in XSD attribute xsi:type</div><div class="line"><a name="l03141"></a><span class="lineno"> 3141</span>&#160;        _ns__name    s    &lt;i&gt;`ns:name`&lt;/i&gt;;  // ref to global ns:name element</div><div class="line"><a name="l03142"></a><span class="lineno"> 3142</span>&#160;        uint64_t     SSN;</div><div class="line"><a name="l03143"></a><span class="lineno"> 3143</span>&#160;        _ns__record *spouse;</div><div class="line"><a name="l03144"></a><span class="lineno"> 3144</span>&#160;    };</div><div class="line"><a name="l03145"></a><span class="lineno"> 3145</span>&#160;~~~</div><div class="line"><a name="l03146"></a><span class="lineno"> 3146</span>&#160;</div><div class="line"><a name="l03147"></a><span class="lineno"> 3147</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l03148"></a><span class="lineno"> 3148</span>&#160;</div><div class="line"><a name="l03149"></a><span class="lineno"> 3149</span>&#160;### (Smart) pointer members and their occurrence constraints         {#toxsd9-8}</div><div class="line"><a name="l03150"></a><span class="lineno"> 3150</span>&#160;</div><div class="line"><a name="l03151"></a><span class="lineno"> 3151</span>&#160;A public pointer-typed data member is serialized by following its (smart)</div><div class="line"><a name="l03152"></a><span class="lineno"> 3152</span>&#160;pointer(s) to the value pointed to.  To serialize pointers to dynamic arrays of</div><div class="line"><a name="l03153"></a><span class="lineno"> 3153</span>&#160;data, please see the next section on</div><div class="line"><a name="l03154"></a><span class="lineno"> 3154</span>&#160;[container and array members and their occurrence constraints](#toxsd9-9).</div><div class="line"><a name="l03155"></a><span class="lineno"> 3155</span>&#160;</div><div class="line"><a name="l03156"></a><span class="lineno"> 3156</span>&#160;Pointers that are NULL and smart pointers that are empty are serialized to</div><div class="line"><a name="l03157"></a><span class="lineno"> 3157</span>&#160;produce omitted element and attribute values, unless an element is required</div><div class="line"><a name="l03158"></a><span class="lineno"> 3158</span>&#160;and is nillable (struct/class members marked with `nullptr`) in which case the</div><div class="line"><a name="l03159"></a><span class="lineno"> 3159</span>&#160;element is rendered as an empty element with &lt;i&gt;`xsi:nil=&quot;true&quot;`&lt;/i&gt;.</div><div class="line"><a name="l03160"></a><span class="lineno"> 3160</span>&#160;</div><div class="line"><a name="l03161"></a><span class="lineno"> 3161</span>&#160;To control the occurrence requirements of pointer-based data members,</div><div class="line"><a name="l03162"></a><span class="lineno"> 3162</span>&#160;occurrence constraints are associated with data members in the form of a range</div><div class="line"><a name="l03163"></a><span class="lineno"> 3163</span>&#160;`minOccurs : maxOccurs`.  For non-repeatable (meaning, not a container or array)</div><div class="line"><a name="l03164"></a><span class="lineno"> 3164</span>&#160;data members, there are only three reasonable occurrence constraints:</div><div class="line"><a name="l03165"></a><span class="lineno"> 3165</span>&#160;</div><div class="line"><a name="l03166"></a><span class="lineno"> 3166</span>&#160;- `0:0` means that this element or attribute is prohibited.</div><div class="line"><a name="l03167"></a><span class="lineno"> 3167</span>&#160;</div><div class="line"><a name="l03168"></a><span class="lineno"> 3168</span>&#160;- `0:1` means that this element or attribute is optional.</div><div class="line"><a name="l03169"></a><span class="lineno"> 3169</span>&#160;</div><div class="line"><a name="l03170"></a><span class="lineno"> 3170</span>&#160;- `1:1` means that this element or attribute is required.</div><div class="line"><a name="l03171"></a><span class="lineno"> 3171</span>&#160;</div><div class="line"><a name="l03172"></a><span class="lineno"> 3172</span>&#160;Pointer-based data members have a default `0:1` occurrence constraint, making</div><div class="line"><a name="l03173"></a><span class="lineno"> 3173</span>&#160;them optional, and their XML schema local element/attribute definition is</div><div class="line"><a name="l03174"></a><span class="lineno"> 3174</span>&#160;marked as nillable.  Non-pointer data members have a default `1:1` occurence</div><div class="line"><a name="l03175"></a><span class="lineno"> 3175</span>&#160;constraint, making them required.</div><div class="line"><a name="l03176"></a><span class="lineno"> 3176</span>&#160;</div><div class="line"><a name="l03177"></a><span class="lineno"> 3177</span>&#160;A `nullptr` occurrence constraint may be applicable to required elements that</div><div class="line"><a name="l03178"></a><span class="lineno"> 3178</span>&#160;are nillable pointer types, thus `nullptr 1:1`.  This indicates that the</div><div class="line"><a name="l03179"></a><span class="lineno"> 3179</span>&#160;element is nillable (can be `NULL` or `nullptr`).  A pointer data member that</div><div class="line"><a name="l03180"></a><span class="lineno"> 3180</span>&#160;is explicitly marked as required and nillable with `nullptr 1:1` will be</div><div class="line"><a name="l03181"></a><span class="lineno"> 3181</span>&#160;serialized as an element with an &lt;i&gt;`xsi:nil`&lt;/i&gt; attribute, thus effectively</div><div class="line"><a name="l03182"></a><span class="lineno"> 3182</span>&#160;revealing the NULL property of its value.</div><div class="line"><a name="l03183"></a><span class="lineno"> 3183</span>&#160;</div><div class="line"><a name="l03184"></a><span class="lineno"> 3184</span>&#160;A non-pointer data member that is explicitly marked as optional with `0:1` will</div><div class="line"><a name="l03185"></a><span class="lineno"> 3185</span>&#160;be set to its default value when no XML value is presented to the deserializer.</div><div class="line"><a name="l03186"></a><span class="lineno"> 3186</span>&#160;A default value can be assigned to a data member that has a primitive type or</div><div class="line"><a name="l03187"></a><span class="lineno"> 3187</span>&#160;is a (smart) pointer to primitive type.</div><div class="line"><a name="l03188"></a><span class="lineno"> 3188</span>&#160;</div><div class="line"><a name="l03189"></a><span class="lineno"> 3189</span>&#160;Consider for example:</div><div class="line"><a name="l03190"></a><span class="lineno"> 3190</span>&#160;</div><div class="line"><a name="l03191"></a><span class="lineno"> 3191</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03192"></a><span class="lineno"> 3192</span>&#160;    class ns__record</div><div class="line"><a name="l03193"></a><span class="lineno"> 3193</span>&#160;    {</div><div class="line"><a name="l03194"></a><span class="lineno"> 3194</span>&#160;     public:</div><div class="line"><a name="l03195"></a><span class="lineno"> 3195</span>&#160;        std::shared_ptr&lt;std::string&gt;  name;               // optional (pointer means minOccurs=0)</div><div class="line"><a name="l03196"></a><span class="lineno"> 3196</span>&#160;        uint64_t                      SSN    0:1 = 999;   // force optional with default 999</div><div class="line"><a name="l03197"></a><span class="lineno"> 3197</span>&#160;        ns__record                   *spouse nullptr 1:1; // force required and nillabe when absent</div><div class="line"><a name="l03198"></a><span class="lineno"> 3198</span>&#160;    };</div><div class="line"><a name="l03199"></a><span class="lineno"> 3199</span>&#160;~~~</div><div class="line"><a name="l03200"></a><span class="lineno"> 3200</span>&#160;</div><div class="line"><a name="l03201"></a><span class="lineno"> 3201</span>&#160;This class maps to a complexType in the soapcpp2-generated XML schema:</div><div class="line"><a name="l03202"></a><span class="lineno"> 3202</span>&#160;</div><div class="line"><a name="l03203"></a><span class="lineno"> 3203</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03204"></a><span class="lineno"> 3204</span>&#160;~~~{.xml}</div><div class="line"><a name="l03205"></a><span class="lineno"> 3205</span>&#160;    &lt;complexType name=&quot;record&quot;&gt;</div><div class="line"><a name="l03206"></a><span class="lineno"> 3206</span>&#160;      &lt;sequence&gt;</div><div class="line"><a name="l03207"></a><span class="lineno"> 3207</span>&#160;        &lt;element name=&quot;name&quot; type=&quot;xsd:string&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot; nillable=&quot;true&quot;/&gt;</div><div class="line"><a name="l03208"></a><span class="lineno"> 3208</span>&#160;        &lt;element name=&quot;SSN&quot; type=&quot;xsd:unsignedLong&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot; default=&quot;999&quot;/&gt;</div><div class="line"><a name="l03209"></a><span class="lineno"> 3209</span>&#160;        &lt;element name=&quot;spouse&quot; type=&quot;ns:record&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot; nillable=&quot;true&quot;/&gt;</div><div class="line"><a name="l03210"></a><span class="lineno"> 3210</span>&#160;      &lt;/sequence&gt;</div><div class="line"><a name="l03211"></a><span class="lineno"> 3211</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l03212"></a><span class="lineno"> 3212</span>&#160;~~~</div><div class="line"><a name="l03213"></a><span class="lineno"> 3213</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03214"></a><span class="lineno"> 3214</span>&#160;</div><div class="line"><a name="l03215"></a><span class="lineno"> 3215</span>&#160;An example XML instance of `ns__record` with its `name` string value set to</div><div class="line"><a name="l03216"></a><span class="lineno"> 3216</span>&#160;`Joe`, `SSN` set to its default, and `spouse` set to NULL:</div><div class="line"><a name="l03217"></a><span class="lineno"> 3217</span>&#160;</div><div class="line"><a name="l03218"></a><span class="lineno"> 3218</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03219"></a><span class="lineno"> 3219</span>&#160;~~~{.xml}</div><div class="line"><a name="l03220"></a><span class="lineno"> 3220</span>&#160;    &lt;ns:record xmlns:ns=&quot;urn:types&quot; ...&gt;</div><div class="line"><a name="l03221"></a><span class="lineno"> 3221</span>&#160;      &lt;name&gt;Joe&lt;/name&gt;</div><div class="line"><a name="l03222"></a><span class="lineno"> 3222</span>&#160;      &lt;SSN&gt;999&lt;/SSN&gt;</div><div class="line"><a name="l03223"></a><span class="lineno"> 3223</span>&#160;      &lt;spouse xsi:nil=&quot;true&quot;/&gt;</div><div class="line"><a name="l03224"></a><span class="lineno"> 3224</span>&#160;    &lt;/ns:record&gt;</div><div class="line"><a name="l03225"></a><span class="lineno"> 3225</span>&#160;~~~</div><div class="line"><a name="l03226"></a><span class="lineno"> 3226</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03227"></a><span class="lineno"> 3227</span>&#160;</div><div class="line"><a name="l03228"></a><span class="lineno"> 3228</span>&#160;@note In general, a smart pointer is simply declared as a `volatile` template</div><div class="line"><a name="l03229"></a><span class="lineno"> 3229</span>&#160;in a interface header file for soapcpp2:</div><div class="line"><a name="l03230"></a><span class="lineno"> 3230</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03231"></a><span class="lineno"> 3231</span>&#160;    volatile template &lt;class T&gt; class NAMESPACE::shared_ptr;</div><div class="line"><a name="l03232"></a><span class="lineno"> 3232</span>&#160;~~~</div><div class="line"><a name="l03233"></a><span class="lineno"> 3233</span>&#160;</div><div class="line"><a name="l03234"></a><span class="lineno"> 3234</span>&#160;@note The soapcpp2 tool generates code that uses `NAMESPACE::shared_ptr` and</div><div class="line"><a name="l03235"></a><span class="lineno"> 3235</span>&#160;`NAMESPACE::make_shared` to create shared pointers to objects, where</div><div class="line"><a name="l03236"></a><span class="lineno"> 3236</span>&#160;`NAMESPACE` is any valid C++ namespace such as `std` and `boost` if you have</div><div class="line"><a name="l03237"></a><span class="lineno"> 3237</span>&#160;Boost installed.</div><div class="line"><a name="l03238"></a><span class="lineno"> 3238</span>&#160;</div><div class="line"><a name="l03239"></a><span class="lineno"> 3239</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l03240"></a><span class="lineno"> 3240</span>&#160;</div><div class="line"><a name="l03241"></a><span class="lineno"> 3241</span>&#160;### Container and array members and their occurrence constraints     {#toxsd9-9}</div><div class="line"><a name="l03242"></a><span class="lineno"> 3242</span>&#160;</div><div class="line"><a name="l03243"></a><span class="lineno"> 3243</span>&#160;Class and struct data member types that are containers `std::deque`,</div><div class="line"><a name="l03244"></a><span class="lineno"> 3244</span>&#160;`std::list`, `std::vector` and `std::set` are serialized as a collection of</div><div class="line"><a name="l03245"></a><span class="lineno"> 3245</span>&#160;the values they contain.  You can also serialize dynamic arrays, which is the</div><div class="line"><a name="l03246"></a><span class="lineno"> 3246</span>&#160;alternative for C to store collections of data.  Let&#39;s start with STL containers.</div><div class="line"><a name="l03247"></a><span class="lineno"> 3247</span>&#160;</div><div class="line"><a name="l03248"></a><span class="lineno"> 3248</span>&#160;You can use `std::deque`, `std::list`, `std::vector`, and `std::set` containers</div><div class="line"><a name="l03249"></a><span class="lineno"> 3249</span>&#160;by importing:</div><div class="line"><a name="l03250"></a><span class="lineno"> 3250</span>&#160;</div><div class="line"><a name="l03251"></a><span class="lineno"> 3251</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03252"></a><span class="lineno"> 3252</span>&#160;    #import &quot;import/stl.h&quot;       // import all containers</div><div class="line"><a name="l03253"></a><span class="lineno"> 3253</span>&#160;    #import &quot;import/stldeque.h&quot;  // import deque</div><div class="line"><a name="l03254"></a><span class="lineno"> 3254</span>&#160;    #import &quot;import/stllist.h&quot;   // import list</div><div class="line"><a name="l03255"></a><span class="lineno"> 3255</span>&#160;    #import &quot;import/stlvector.h&quot; // import vector</div><div class="line"><a name="l03256"></a><span class="lineno"> 3256</span>&#160;    #import &quot;import/stlset.h&quot;    // import set</div><div class="line"><a name="l03257"></a><span class="lineno"> 3257</span>&#160;~~~</div><div class="line"><a name="l03258"></a><span class="lineno"> 3258</span>&#160;</div><div class="line"><a name="l03259"></a><span class="lineno"> 3259</span>&#160;For example, to use a vector data mamber to store names in a record:</div><div class="line"><a name="l03260"></a><span class="lineno"> 3260</span>&#160;</div><div class="line"><a name="l03261"></a><span class="lineno"> 3261</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03262"></a><span class="lineno"> 3262</span>&#160;    #import &quot;import/stlvector.h&quot;</div><div class="line"><a name="l03263"></a><span class="lineno"> 3263</span>&#160;    class ns__record</div><div class="line"><a name="l03264"></a><span class="lineno"> 3264</span>&#160;    {</div><div class="line"><a name="l03265"></a><span class="lineno"> 3265</span>&#160;     public:</div><div class="line"><a name="l03266"></a><span class="lineno"> 3266</span>&#160;        std::vector&lt;std::string&gt;  names;</div><div class="line"><a name="l03267"></a><span class="lineno"> 3267</span>&#160;        uint64_t                  SSN;</div><div class="line"><a name="l03268"></a><span class="lineno"> 3268</span>&#160;    };</div><div class="line"><a name="l03269"></a><span class="lineno"> 3269</span>&#160;~~~</div><div class="line"><a name="l03270"></a><span class="lineno"> 3270</span>&#160;</div><div class="line"><a name="l03271"></a><span class="lineno"> 3271</span>&#160;To limit the number of names in the vector within reasonable bounds, occurrence</div><div class="line"><a name="l03272"></a><span class="lineno"> 3272</span>&#160;constraints are associated with the container.  Occurrence constraints are of</div><div class="line"><a name="l03273"></a><span class="lineno"> 3273</span>&#160;the form `minOccurs : maxOccurs`:</div><div class="line"><a name="l03274"></a><span class="lineno"> 3274</span>&#160;</div><div class="line"><a name="l03275"></a><span class="lineno"> 3275</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03276"></a><span class="lineno"> 3276</span>&#160;    #import &quot;import/stlvector.h&quot;</div><div class="line"><a name="l03277"></a><span class="lineno"> 3277</span>&#160;    class ns__record</div><div class="line"><a name="l03278"></a><span class="lineno"> 3278</span>&#160;    {</div><div class="line"><a name="l03279"></a><span class="lineno"> 3279</span>&#160;     public:</div><div class="line"><a name="l03280"></a><span class="lineno"> 3280</span>&#160;        std::vector&lt;std::string&gt;  names 1:10;</div><div class="line"><a name="l03281"></a><span class="lineno"> 3281</span>&#160;        uint64_t                  SSN;</div><div class="line"><a name="l03282"></a><span class="lineno"> 3282</span>&#160;    };</div><div class="line"><a name="l03283"></a><span class="lineno"> 3283</span>&#160;~~~</div><div class="line"><a name="l03284"></a><span class="lineno"> 3284</span>&#160;</div><div class="line"><a name="l03285"></a><span class="lineno"> 3285</span>&#160;This class maps to a complexType in the soapcpp2-generated XML schema:</div><div class="line"><a name="l03286"></a><span class="lineno"> 3286</span>&#160;</div><div class="line"><a name="l03287"></a><span class="lineno"> 3287</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03288"></a><span class="lineno"> 3288</span>&#160;~~~{.xml}</div><div class="line"><a name="l03289"></a><span class="lineno"> 3289</span>&#160;    &lt;complexType name=&quot;record&quot;&gt;</div><div class="line"><a name="l03290"></a><span class="lineno"> 3290</span>&#160;      &lt;sequence&gt;</div><div class="line"><a name="l03291"></a><span class="lineno"> 3291</span>&#160;        &lt;element name=&quot;name&quot; type=&quot;xsd:string&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;10&quot;/&gt;</div><div class="line"><a name="l03292"></a><span class="lineno"> 3292</span>&#160;        &lt;element name=&quot;SSN&quot; type=&quot;xsd:unsignedLong&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03293"></a><span class="lineno"> 3293</span>&#160;      &lt;/sequence&gt;</div><div class="line"><a name="l03294"></a><span class="lineno"> 3294</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l03295"></a><span class="lineno"> 3295</span>&#160;~~~</div><div class="line"><a name="l03296"></a><span class="lineno"> 3296</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03297"></a><span class="lineno"> 3297</span>&#160;</div><div class="line"><a name="l03298"></a><span class="lineno"> 3298</span>&#160;@note In general, a container is simply declared as a template in an interface</div><div class="line"><a name="l03299"></a><span class="lineno"> 3299</span>&#160;header file for soapcpp2.  All class templates are considered containers</div><div class="line"><a name="l03300"></a><span class="lineno"> 3300</span>&#160;(except when declared `volatile`, see smart pointers).  For example,</div><div class="line"><a name="l03301"></a><span class="lineno"> 3301</span>&#160;`std::vector` is declared in &lt;i&gt;`gsoap/import/stlvector.h`&lt;/i&gt; as:</div><div class="line"><a name="l03302"></a><span class="lineno"> 3302</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03303"></a><span class="lineno"> 3303</span>&#160;    template &lt;class T&gt; class std::vector;</div><div class="line"><a name="l03304"></a><span class="lineno"> 3304</span>&#160;~~~</div><div class="line"><a name="l03305"></a><span class="lineno"> 3305</span>&#160;</div><div class="line"><a name="l03306"></a><span class="lineno"> 3306</span>&#160;@note You can define and use your own containers.  The soapcpp2 tool generates</div><div class="line"><a name="l03307"></a><span class="lineno"> 3307</span>&#160;code that uses the following members of the `template &lt;typename T&gt; class C`</div><div class="line"><a name="l03308"></a><span class="lineno"> 3308</span>&#160;container:</div><div class="line"><a name="l03309"></a><span class="lineno"> 3309</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03310"></a><span class="lineno"> 3310</span>&#160;    void              C::clear()</div><div class="line"><a name="l03311"></a><span class="lineno"> 3311</span>&#160;    C::iterator       C::begin()</div><div class="line"><a name="l03312"></a><span class="lineno"> 3312</span>&#160;    C::const_iterator C::begin() const</div><div class="line"><a name="l03313"></a><span class="lineno"> 3313</span>&#160;    C::iterator       C::end()</div><div class="line"><a name="l03314"></a><span class="lineno"> 3314</span>&#160;    C::const_iterator C::end() const</div><div class="line"><a name="l03315"></a><span class="lineno"> 3315</span>&#160;    size_t            C::size() const</div><div class="line"><a name="l03316"></a><span class="lineno"> 3316</span>&#160;    C::iterator       C::insert(C::iterator pos, const T&amp; val)</div><div class="line"><a name="l03317"></a><span class="lineno"> 3317</span>&#160;~~~</div><div class="line"><a name="l03318"></a><span class="lineno"> 3318</span>&#160;</div><div class="line"><a name="l03319"></a><span class="lineno"> 3319</span>&#160;@note For more details see the example `simple_vector` container with</div><div class="line"><a name="l03320"></a><span class="lineno"> 3320</span>&#160;documentation in the package under &lt;i&gt;`gsoap/samples/template`&lt;/i&gt;.</div><div class="line"><a name="l03321"></a><span class="lineno"> 3321</span>&#160;</div><div class="line"><a name="l03322"></a><span class="lineno"> 3322</span>&#160;Because C does not support a container template library, we can use a</div><div class="line"><a name="l03323"></a><span class="lineno"> 3323</span>&#160;dynamically-sized array of values.  This array is declared as a size-pointer</div><div class="line"><a name="l03324"></a><span class="lineno"> 3324</span>&#160;pair of members within a struct or class.  The array size information is stored</div><div class="line"><a name="l03325"></a><span class="lineno"> 3325</span>&#160;in a special size tag member with the name `__size` or `__sizeX`, where `X` can</div><div class="line"><a name="l03326"></a><span class="lineno"> 3326</span>&#160;be any name, or by an `$int` member to identify the member as a special size</div><div class="line"><a name="l03327"></a><span class="lineno"> 3327</span>&#160;tag:</div><div class="line"><a name="l03328"></a><span class="lineno"> 3328</span>&#160;</div><div class="line"><a name="l03329"></a><span class="lineno"> 3329</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03330"></a><span class="lineno"> 3330</span>&#160;    struct ns__record</div><div class="line"><a name="l03331"></a><span class="lineno"> 3331</span>&#160;    {</div><div class="line"><a name="l03332"></a><span class="lineno"> 3332</span>&#160;      $ int      sizeofnames; // array size</div><div class="line"><a name="l03333"></a><span class="lineno"> 3333</span>&#160;        char*    *names;       // array of char* names</div><div class="line"><a name="l03334"></a><span class="lineno"> 3334</span>&#160;        uint64_t  SSN;</div><div class="line"><a name="l03335"></a><span class="lineno"> 3335</span>&#160;    };</div><div class="line"><a name="l03336"></a><span class="lineno"> 3336</span>&#160;~~~</div><div class="line"><a name="l03337"></a><span class="lineno"> 3337</span>&#160;</div><div class="line"><a name="l03338"></a><span class="lineno"> 3338</span>&#160;This struct maps to a complexType in the soapcpp2-generated XML schema:</div><div class="line"><a name="l03339"></a><span class="lineno"> 3339</span>&#160;</div><div class="line"><a name="l03340"></a><span class="lineno"> 3340</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03341"></a><span class="lineno"> 3341</span>&#160;~~~{.xml}</div><div class="line"><a name="l03342"></a><span class="lineno"> 3342</span>&#160;    &lt;complexType name=&quot;record&quot;&gt;</div><div class="line"><a name="l03343"></a><span class="lineno"> 3343</span>&#160;      &lt;sequence&gt;</div><div class="line"><a name="l03344"></a><span class="lineno"> 3344</span>&#160;        &lt;element name=&quot;name&quot; type=&quot;xsd:string&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;unbounded&quot; nillable=&quot;true&quot;/&gt;</div><div class="line"><a name="l03345"></a><span class="lineno"> 3345</span>&#160;        &lt;element name=&quot;SSN&quot; type=&quot;xsd:unsignedLong&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03346"></a><span class="lineno"> 3346</span>&#160;      &lt;/sequence&gt;</div><div class="line"><a name="l03347"></a><span class="lineno"> 3347</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l03348"></a><span class="lineno"> 3348</span>&#160;~~~</div><div class="line"><a name="l03349"></a><span class="lineno"> 3349</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03350"></a><span class="lineno"> 3350</span>&#160;</div><div class="line"><a name="l03351"></a><span class="lineno"> 3351</span>&#160;To limit the number of names in the array within reasonable bounds, occurrence</div><div class="line"><a name="l03352"></a><span class="lineno"> 3352</span>&#160;constraints are associated with the array size member.  Occurrence constraints</div><div class="line"><a name="l03353"></a><span class="lineno"> 3353</span>&#160;are of the form `minOccurs : maxOccurs`:</div><div class="line"><a name="l03354"></a><span class="lineno"> 3354</span>&#160;</div><div class="line"><a name="l03355"></a><span class="lineno"> 3355</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03356"></a><span class="lineno"> 3356</span>&#160;    struct ns__record</div><div class="line"><a name="l03357"></a><span class="lineno"> 3357</span>&#160;    {</div><div class="line"><a name="l03358"></a><span class="lineno"> 3358</span>&#160;      $ int      sizeofnames 1:10; // array size 1..10</div><div class="line"><a name="l03359"></a><span class="lineno"> 3359</span>&#160;        char*   *names;            // array of one to ten char* names</div><div class="line"><a name="l03360"></a><span class="lineno"> 3360</span>&#160;        uint64_t SSN;</div><div class="line"><a name="l03361"></a><span class="lineno"> 3361</span>&#160;    };</div><div class="line"><a name="l03362"></a><span class="lineno"> 3362</span>&#160;~~~</div><div class="line"><a name="l03363"></a><span class="lineno"> 3363</span>&#160;</div><div class="line"><a name="l03364"></a><span class="lineno"> 3364</span>&#160;This struct maps to a complexType in the soapcpp2-generated XML schema:</div><div class="line"><a name="l03365"></a><span class="lineno"> 3365</span>&#160;</div><div class="line"><a name="l03366"></a><span class="lineno"> 3366</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03367"></a><span class="lineno"> 3367</span>&#160;~~~{.xml}</div><div class="line"><a name="l03368"></a><span class="lineno"> 3368</span>&#160;    &lt;complexType name=&quot;record&quot;&gt;</div><div class="line"><a name="l03369"></a><span class="lineno"> 3369</span>&#160;      &lt;sequence&gt;</div><div class="line"><a name="l03370"></a><span class="lineno"> 3370</span>&#160;        &lt;element name=&quot;name&quot; type=&quot;xsd:string&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;10&quot; nillable=&quot;true&quot;/&gt;</div><div class="line"><a name="l03371"></a><span class="lineno"> 3371</span>&#160;        &lt;element name=&quot;SSN&quot; type=&quot;xsd:unsignedLong&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03372"></a><span class="lineno"> 3372</span>&#160;      &lt;/sequence&gt;</div><div class="line"><a name="l03373"></a><span class="lineno"> 3373</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l03374"></a><span class="lineno"> 3374</span>&#160;~~~</div><div class="line"><a name="l03375"></a><span class="lineno"> 3375</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03376"></a><span class="lineno"> 3376</span>&#160;</div><div class="line"><a name="l03377"></a><span class="lineno"> 3377</span>&#160;Arrays can also be declared as nested elements, similar to SOAP-encoded dynamic arrays, and these arrays can be used with or without SOAP applications.  This requires a separate struct or class with the name of the SOAP array, which should not be qualified with a namespace prefix:</div><div class="line"><a name="l03378"></a><span class="lineno"> 3378</span>&#160;</div><div class="line"><a name="l03379"></a><span class="lineno"> 3379</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03380"></a><span class="lineno"> 3380</span>&#160;    struct ArrayOfstring</div><div class="line"><a name="l03381"></a><span class="lineno"> 3381</span>&#160;    {</div><div class="line"><a name="l03382"></a><span class="lineno"> 3382</span>&#160;        char* *__ptr 1:100; // array of 1..100 strings</div><div class="line"><a name="l03383"></a><span class="lineno"> 3383</span>&#160;        int    __size;      // array size</div><div class="line"><a name="l03384"></a><span class="lineno"> 3384</span>&#160;    };</div><div class="line"><a name="l03385"></a><span class="lineno"> 3385</span>&#160;    struct ns__record</div><div class="line"><a name="l03386"></a><span class="lineno"> 3386</span>&#160;    {</div><div class="line"><a name="l03387"></a><span class="lineno"> 3387</span>&#160;        struct ArrayOfstring names; // array of char* names</div><div class="line"><a name="l03388"></a><span class="lineno"> 3388</span>&#160;        uint64_t             SSN;</div><div class="line"><a name="l03389"></a><span class="lineno"> 3389</span>&#160;    };</div><div class="line"><a name="l03390"></a><span class="lineno"> 3390</span>&#160;~~~</div><div class="line"><a name="l03391"></a><span class="lineno"> 3391</span>&#160;</div><div class="line"><a name="l03392"></a><span class="lineno"> 3392</span>&#160;The `ns__record` struct maps to a complexType that references the &lt;i&gt;`ArrayOfstring`&lt;/i&gt; complexType with an sequence of 1 to 100 &lt;i&gt;`item`&lt;/i&gt; elements:</div><div class="line"><a name="l03393"></a><span class="lineno"> 3393</span>&#160;</div><div class="line"><a name="l03394"></a><span class="lineno"> 3394</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03395"></a><span class="lineno"> 3395</span>&#160;~~~{.xml}</div><div class="line"><a name="l03396"></a><span class="lineno"> 3396</span>&#160;    &lt;complexType name=&quot;ArrayOfstring&quot;&gt;</div><div class="line"><a name="l03397"></a><span class="lineno"> 3397</span>&#160;      &lt;sequence&gt;</div><div class="line"><a name="l03398"></a><span class="lineno"> 3398</span>&#160;        &lt;element name=&quot;item&quot; type=&quot;xsd:string&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;100&quot;/&gt;</div><div class="line"><a name="l03399"></a><span class="lineno"> 3399</span>&#160;      &lt;/sequence&gt;</div><div class="line"><a name="l03400"></a><span class="lineno"> 3400</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l03401"></a><span class="lineno"> 3401</span>&#160;    &lt;complexType name=&quot;record&quot;&gt;</div><div class="line"><a name="l03402"></a><span class="lineno"> 3402</span>&#160;      &lt;sequence&gt;</div><div class="line"><a name="l03403"></a><span class="lineno"> 3403</span>&#160;        &lt;element name=&quot;names&quot; type=&quot;ns:ArrayOfstring&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03404"></a><span class="lineno"> 3404</span>&#160;        &lt;element name=&quot;SSN&quot; type=&quot;xsd:unsignedLong&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03405"></a><span class="lineno"> 3405</span>&#160;      &lt;/sequence&gt;</div><div class="line"><a name="l03406"></a><span class="lineno"> 3406</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l03407"></a><span class="lineno"> 3407</span>&#160;~~~</div><div class="line"><a name="l03408"></a><span class="lineno"> 3408</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03409"></a><span class="lineno"> 3409</span>&#160;</div><div class="line"><a name="l03410"></a><span class="lineno"> 3410</span>&#160;To change the &lt;i&gt;`item`&lt;/i&gt; element name in the WSDL, XML schema, and XML messages, use `__ptrName` where `Name` is the name you want to use.</div><div class="line"><a name="l03411"></a><span class="lineno"> 3411</span>&#160;</div><div class="line"><a name="l03412"></a><span class="lineno"> 3412</span>&#160;@note When &lt;b&gt;`soapcpp2 -e`&lt;/b&gt; option &lt;b&gt;`-e`&lt;/b&gt; is used, the &lt;i&gt;`ArrayOfstring`&lt;/i&gt; becomes a SOAP-encoded array for SOAP 1.1/1.2 RPC encoded messaging:</div><div class="line"><a name="l03413"></a><span class="lineno"> 3413</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03414"></a><span class="lineno"> 3414</span>&#160;~~~{.xml}</div><div class="line"><a name="l03415"></a><span class="lineno"> 3415</span>&#160;    &lt;import namespace=&quot;http://schemas.xmlsoap.org/soap/encoding/&quot;/&gt;</div><div class="line"><a name="l03416"></a><span class="lineno"> 3416</span>&#160;    &lt;complexType name=&quot;ArrayOfstring&quot;&gt;</div><div class="line"><a name="l03417"></a><span class="lineno"> 3417</span>&#160;      &lt;complexContent&gt;</div><div class="line"><a name="l03418"></a><span class="lineno"> 3418</span>&#160;        &lt;restriction base=&quot;SOAP-ENC:Array&quot;&gt;</div><div class="line"><a name="l03419"></a><span class="lineno"> 3419</span>&#160;          &lt;sequence&gt;</div><div class="line"><a name="l03420"></a><span class="lineno"> 3420</span>&#160;            &lt;element name=&quot;item&quot; type=&quot;xsd:string&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;100&quot;/&gt;</div><div class="line"><a name="l03421"></a><span class="lineno"> 3421</span>&#160;          &lt;/sequence&gt;</div><div class="line"><a name="l03422"></a><span class="lineno"> 3422</span>&#160;          &lt;attribute ref=&quot;SOAP-ENC:arrayType&quot; WSDL:arrayType=&quot;xsd:string[]&quot;/&gt;</div><div class="line"><a name="l03423"></a><span class="lineno"> 3423</span>&#160;        &lt;/restriction&gt;</div><div class="line"><a name="l03424"></a><span class="lineno"> 3424</span>&#160;      &lt;/complexContent&gt;</div><div class="line"><a name="l03425"></a><span class="lineno"> 3425</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l03426"></a><span class="lineno"> 3426</span>&#160;    &lt;complexType name=&quot;record&quot;&gt;</div><div class="line"><a name="l03427"></a><span class="lineno"> 3427</span>&#160;      &lt;sequence&gt;</div><div class="line"><a name="l03428"></a><span class="lineno"> 3428</span>&#160;        &lt;element name=&quot;names&quot; type=&quot;ns:ArrayOfstring&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03429"></a><span class="lineno"> 3429</span>&#160;        &lt;element name=&quot;SSN&quot; type=&quot;xsd:unsignedLong&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03430"></a><span class="lineno"> 3430</span>&#160;      &lt;/sequence&gt;</div><div class="line"><a name="l03431"></a><span class="lineno"> 3431</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l03432"></a><span class="lineno"> 3432</span>&#160;~~~</div><div class="line"><a name="l03433"></a><span class="lineno"> 3433</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03434"></a><span class="lineno"> 3434</span>&#160;</div><div class="line"><a name="l03435"></a><span class="lineno"> 3435</span>&#160;Fixed-size arrays can be used to store a fixed number of values:</div><div class="line"><a name="l03436"></a><span class="lineno"> 3436</span>&#160;</div><div class="line"><a name="l03437"></a><span class="lineno"> 3437</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03438"></a><span class="lineno"> 3438</span>&#160;    struct ns__record</div><div class="line"><a name="l03439"></a><span class="lineno"> 3439</span>&#160;    {</div><div class="line"><a name="l03440"></a><span class="lineno"> 3440</span>&#160;        char*    names[10]; // array of 10 char* names</div><div class="line"><a name="l03441"></a><span class="lineno"> 3441</span>&#160;        uint64_t SSN;</div><div class="line"><a name="l03442"></a><span class="lineno"> 3442</span>&#160;    };</div><div class="line"><a name="l03443"></a><span class="lineno"> 3443</span>&#160;~~~</div><div class="line"><a name="l03444"></a><span class="lineno"> 3444</span>&#160;</div><div class="line"><a name="l03445"></a><span class="lineno"> 3445</span>&#160;The fixed-size array is similar to a SOAP-encoded array, which can be used with or without SOAP applications.  This struct maps to a complexType that references a &lt;i&gt;`Array10Ofstring`&lt;/i&gt; complexType with ten &lt;i&gt;`item`&lt;/i&gt; elements:</div><div class="line"><a name="l03446"></a><span class="lineno"> 3446</span>&#160;</div><div class="line"><a name="l03447"></a><span class="lineno"> 3447</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03448"></a><span class="lineno"> 3448</span>&#160;~~~{.xml}</div><div class="line"><a name="l03449"></a><span class="lineno"> 3449</span>&#160;    &lt;complexType name=&quot;record&quot;&gt;</div><div class="line"><a name="l03450"></a><span class="lineno"> 3450</span>&#160;      &lt;sequence&gt;</div><div class="line"><a name="l03451"></a><span class="lineno"> 3451</span>&#160;        &lt;element name=&quot;names&quot; type=&quot;ns:Array10Ofstring&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03452"></a><span class="lineno"> 3452</span>&#160;        &lt;element name=&quot;SSN&quot; type=&quot;xsd:unsignedLong&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03453"></a><span class="lineno"> 3453</span>&#160;      &lt;/sequence&gt;</div><div class="line"><a name="l03454"></a><span class="lineno"> 3454</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l03455"></a><span class="lineno"> 3455</span>&#160;    &lt;complexType name=&quot;Array10Ofstring&quot;&gt;</div><div class="line"><a name="l03456"></a><span class="lineno"> 3456</span>&#160;      &lt;sequence&gt;</div><div class="line"><a name="l03457"></a><span class="lineno"> 3457</span>&#160;        &lt;element name=&quot;item&quot; type=&quot;xsd:string&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;10&quot;/&gt;</div><div class="line"><a name="l03458"></a><span class="lineno"> 3458</span>&#160;      &lt;/sequence&gt;</div><div class="line"><a name="l03459"></a><span class="lineno"> 3459</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l03460"></a><span class="lineno"> 3460</span>&#160;~~~</div><div class="line"><a name="l03461"></a><span class="lineno"> 3461</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03462"></a><span class="lineno"> 3462</span>&#160;</div><div class="line"><a name="l03463"></a><span class="lineno"> 3463</span>&#160;@note When &lt;b&gt;`soapcpp2 -e`&lt;/b&gt; option &lt;b&gt;`-e`&lt;/b&gt; is used, the &lt;i&gt;`Array10Ofstring`&lt;/i&gt; becomes a SOAP-encoded array for SOAP 1.1/1.2 RPC encoded messaging, see previous note.</div><div class="line"><a name="l03464"></a><span class="lineno"> 3464</span>&#160;</div><div class="line"><a name="l03465"></a><span class="lineno"> 3465</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l03466"></a><span class="lineno"> 3466</span>&#160;</div><div class="line"><a name="l03467"></a><span class="lineno"> 3467</span>&#160;### Sequencing with hidden members                                  {#toxsd9-10}</div><div class="line"><a name="l03468"></a><span class="lineno"> 3468</span>&#160;</div><div class="line"><a name="l03469"></a><span class="lineno"> 3469</span>&#160;A member becomes a hidden XML element, i.e. not visibly rendered in XML, when</div><div class="line"><a name="l03470"></a><span class="lineno"> 3470</span>&#160;its name starts with a double underscore.  This makes it possible to sequence a</div><div class="line"><a name="l03471"></a><span class="lineno"> 3471</span>&#160;collection of data members, basically by forming a sequence of elements that</div><div class="line"><a name="l03472"></a><span class="lineno"> 3472</span>&#160;can be optional or repeated together.</div><div class="line"><a name="l03473"></a><span class="lineno"> 3473</span>&#160;</div><div class="line"><a name="l03474"></a><span class="lineno"> 3474</span>&#160;To create a sequence of members that are optional, use a pointer-based hidden</div><div class="line"><a name="l03475"></a><span class="lineno"> 3475</span>&#160;member that is a struct with the collection of members to sequence:</div><div class="line"><a name="l03476"></a><span class="lineno"> 3476</span>&#160;</div><div class="line"><a name="l03477"></a><span class="lineno"> 3477</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03478"></a><span class="lineno"> 3478</span>&#160;    struct ns__record</div><div class="line"><a name="l03479"></a><span class="lineno"> 3479</span>&#160;    {</div><div class="line"><a name="l03480"></a><span class="lineno"> 3480</span>&#160;        std::string   name;       // required name</div><div class="line"><a name="l03481"></a><span class="lineno"> 3481</span>&#160;        struct __ns__optional</div><div class="line"><a name="l03482"></a><span class="lineno"> 3482</span>&#160;        {</div><div class="line"><a name="l03483"></a><span class="lineno"> 3483</span>&#160;            uint64_t    SSN;      // SSN in optional group</div><div class="line"><a name="l03484"></a><span class="lineno"> 3484</span>&#160;            std::string phone;    // phone number in optional group</div><div class="line"><a name="l03485"></a><span class="lineno"> 3485</span>&#160;        } *__optional;            // optional group</div><div class="line"><a name="l03486"></a><span class="lineno"> 3486</span>&#160;    };</div><div class="line"><a name="l03487"></a><span class="lineno"> 3487</span>&#160;~~~</div><div class="line"><a name="l03488"></a><span class="lineno"> 3488</span>&#160;</div><div class="line"><a name="l03489"></a><span class="lineno"> 3489</span>&#160;Here we used a hidden struct type `__ns__optional` which starts with a double</div><div class="line"><a name="l03490"></a><span class="lineno"> 3490</span>&#160;underscore, because we do not want to define a new global type for the XML</div><div class="line"><a name="l03491"></a><span class="lineno"> 3491</span>&#160;schema we generate.  We just need a unique name for a structure that sequences</div><div class="line"><a name="l03492"></a><span class="lineno"> 3492</span>&#160;the two members.</div><div class="line"><a name="l03493"></a><span class="lineno"> 3493</span>&#160;</div><div class="line"><a name="l03494"></a><span class="lineno"> 3494</span>&#160;This struct maps to a complexType in the soapcpp2-generated XML schema:</div><div class="line"><a name="l03495"></a><span class="lineno"> 3495</span>&#160;</div><div class="line"><a name="l03496"></a><span class="lineno"> 3496</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03497"></a><span class="lineno"> 3497</span>&#160;~~~{.xml}</div><div class="line"><a name="l03498"></a><span class="lineno"> 3498</span>&#160;    &lt;complexType name=&quot;record&quot;&gt;</div><div class="line"><a name="l03499"></a><span class="lineno"> 3499</span>&#160;      &lt;sequence&gt;</div><div class="line"><a name="l03500"></a><span class="lineno"> 3500</span>&#160;        &lt;element name=&quot;name&quot; type=&quot;xsd:string&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03501"></a><span class="lineno"> 3501</span>&#160;        &lt;sequence minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot;&gt;</div><div class="line"><a name="l03502"></a><span class="lineno"> 3502</span>&#160;          &lt;element name=&quot;SSN&quot; type=&quot;xsd:unsignedLong&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03503"></a><span class="lineno"> 3503</span>&#160;          &lt;element name=&quot;phone&quot; type=&quot;xsd:string&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03504"></a><span class="lineno"> 3504</span>&#160;        &lt;/sequence&gt;</div><div class="line"><a name="l03505"></a><span class="lineno"> 3505</span>&#160;      &lt;/sequence&gt;</div><div class="line"><a name="l03506"></a><span class="lineno"> 3506</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l03507"></a><span class="lineno"> 3507</span>&#160;~~~</div><div class="line"><a name="l03508"></a><span class="lineno"> 3508</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03509"></a><span class="lineno"> 3509</span>&#160;</div><div class="line"><a name="l03510"></a><span class="lineno"> 3510</span>&#160;The `name` member is a required element of the &lt;i&gt;`ns:record`&lt;/i&gt; complexType.</div><div class="line"><a name="l03511"></a><span class="lineno"> 3511</span>&#160;The &lt;i&gt;`ns:record`&lt;/i&gt; complexType has an optional sequence of `SSN` and</div><div class="line"><a name="l03512"></a><span class="lineno"> 3512</span>&#160;`phone` elements.</div><div class="line"><a name="l03513"></a><span class="lineno"> 3513</span>&#160;</div><div class="line"><a name="l03514"></a><span class="lineno"> 3514</span>&#160;To create repetitions of a sequence of members, use an array as follows:</div><div class="line"><a name="l03515"></a><span class="lineno"> 3515</span>&#160;</div><div class="line"><a name="l03516"></a><span class="lineno"> 3516</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03517"></a><span class="lineno"> 3517</span>&#160;    struct ns__record</div><div class="line"><a name="l03518"></a><span class="lineno"> 3518</span>&#160;    {</div><div class="line"><a name="l03519"></a><span class="lineno"> 3519</span>&#160;        std::string   name;        // required name</div><div class="line"><a name="l03520"></a><span class="lineno"> 3520</span>&#160;      $ int           sizeofarray; // size of group array</div><div class="line"><a name="l03521"></a><span class="lineno"> 3521</span>&#160;        struct __ns__array</div><div class="line"><a name="l03522"></a><span class="lineno"> 3522</span>&#160;        {</div><div class="line"><a name="l03523"></a><span class="lineno"> 3523</span>&#160;            uint64_t    SSN;       // SSN in group</div><div class="line"><a name="l03524"></a><span class="lineno"> 3524</span>&#160;            std::string phone;     // phone number in group</div><div class="line"><a name="l03525"></a><span class="lineno"> 3525</span>&#160;        } *__array;                // group array</div><div class="line"><a name="l03526"></a><span class="lineno"> 3526</span>&#160;    };</div><div class="line"><a name="l03527"></a><span class="lineno"> 3527</span>&#160;~~~</div><div class="line"><a name="l03528"></a><span class="lineno"> 3528</span>&#160;</div><div class="line"><a name="l03529"></a><span class="lineno"> 3529</span>&#160;This struct maps to a complexType in the soapcpp2-generated XML schema:</div><div class="line"><a name="l03530"></a><span class="lineno"> 3530</span>&#160;</div><div class="line"><a name="l03531"></a><span class="lineno"> 3531</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03532"></a><span class="lineno"> 3532</span>&#160;~~~{.xml}</div><div class="line"><a name="l03533"></a><span class="lineno"> 3533</span>&#160;    &lt;complexType name=&quot;record&quot;&gt;</div><div class="line"><a name="l03534"></a><span class="lineno"> 3534</span>&#160;      &lt;sequence&gt;</div><div class="line"><a name="l03535"></a><span class="lineno"> 3535</span>&#160;        &lt;element name=&quot;name&quot; type=&quot;xsd:string&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03536"></a><span class="lineno"> 3536</span>&#160;        &lt;sequence minOccurs=&quot;0&quot; maxOccurs=&quot;unbounded&quot;&gt;</div><div class="line"><a name="l03537"></a><span class="lineno"> 3537</span>&#160;          &lt;element name=&quot;SSN&quot; type=&quot;xsd:unsignedLong&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03538"></a><span class="lineno"> 3538</span>&#160;          &lt;element name=&quot;phone&quot; type=&quot;xsd:string&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03539"></a><span class="lineno"> 3539</span>&#160;        &lt;/sequence&gt;</div><div class="line"><a name="l03540"></a><span class="lineno"> 3540</span>&#160;      &lt;/sequence&gt;</div><div class="line"><a name="l03541"></a><span class="lineno"> 3541</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l03542"></a><span class="lineno"> 3542</span>&#160;~~~</div><div class="line"><a name="l03543"></a><span class="lineno"> 3543</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03544"></a><span class="lineno"> 3544</span>&#160;</div><div class="line"><a name="l03545"></a><span class="lineno"> 3545</span>&#160;The `name` member is a required element of the &lt;i&gt;`ns:record`&lt;/i&gt; complexType.</div><div class="line"><a name="l03546"></a><span class="lineno"> 3546</span>&#160;The &lt;i&gt;`ns:record`&lt;/i&gt; complexType has a potentially unbounded sequence of</div><div class="line"><a name="l03547"></a><span class="lineno"> 3547</span>&#160;`SSN` and `phone` elements.  You can specify array bounds instead of zero to</div><div class="line"><a name="l03548"></a><span class="lineno"> 3548</span>&#160;unbounded, see [container and array members and their occurrence constraints](#toxsd9-9).</div><div class="line"><a name="l03549"></a><span class="lineno"> 3549</span>&#160;</div><div class="line"><a name="l03550"></a><span class="lineno"> 3550</span>&#160;The XML value space consists of a sequence of SSN and phone elements:</div><div class="line"><a name="l03551"></a><span class="lineno"> 3551</span>&#160;</div><div class="line"><a name="l03552"></a><span class="lineno"> 3552</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03553"></a><span class="lineno"> 3553</span>&#160;~~~{.xml}</div><div class="line"><a name="l03554"></a><span class="lineno"> 3554</span>&#160;    &lt;ns:record&gt;</div><div class="line"><a name="l03555"></a><span class="lineno"> 3555</span>&#160;      &lt;name&gt;numbers&lt;/name&gt;</div><div class="line"><a name="l03556"></a><span class="lineno"> 3556</span>&#160;      &lt;SSN&gt;1234567890&lt;/SSN&gt;</div><div class="line"><a name="l03557"></a><span class="lineno"> 3557</span>&#160;      &lt;phone&gt;555-123-4567&lt;/phone&gt;</div><div class="line"><a name="l03558"></a><span class="lineno"> 3558</span>&#160;      &lt;SSN&gt;1987654320&lt;/SSN&gt;</div><div class="line"><a name="l03559"></a><span class="lineno"> 3559</span>&#160;      &lt;phone&gt;555-789-1234&lt;/phone&gt;</div><div class="line"><a name="l03560"></a><span class="lineno"> 3560</span>&#160;      &lt;SSN&gt;2345678901&lt;/SSN&gt;</div><div class="line"><a name="l03561"></a><span class="lineno"> 3561</span>&#160;      &lt;phone&gt;555-987-6543&lt;/phone&gt;</div><div class="line"><a name="l03562"></a><span class="lineno"> 3562</span>&#160;    &lt;/ns:record&gt;</div><div class="line"><a name="l03563"></a><span class="lineno"> 3563</span>&#160;~~~</div><div class="line"><a name="l03564"></a><span class="lineno"> 3564</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03565"></a><span class="lineno"> 3565</span>&#160;</div><div class="line"><a name="l03566"></a><span class="lineno"> 3566</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l03567"></a><span class="lineno"> 3567</span>&#160;</div><div class="line"><a name="l03568"></a><span class="lineno"> 3568</span>&#160;### Tagged union members                                            {#toxsd9-11}</div><div class="line"><a name="l03569"></a><span class="lineno"> 3569</span>&#160;</div><div class="line"><a name="l03570"></a><span class="lineno"> 3570</span>&#160;A union member in a class or in a struct cannot be serialized unless a</div><div class="line"><a name="l03571"></a><span class="lineno"> 3571</span>&#160;discriminating *variant selector* member is provided that tells the serializer</div><div class="line"><a name="l03572"></a><span class="lineno"> 3572</span>&#160;which union field to serialize.  This effectively creates a *tagged union*.</div><div class="line"><a name="l03573"></a><span class="lineno"> 3573</span>&#160;</div><div class="line"><a name="l03574"></a><span class="lineno"> 3574</span>&#160;The variant selector is associated with the union as a selector-union pair of members.</div><div class="line"><a name="l03575"></a><span class="lineno"> 3575</span>&#160;The variant selector is a member with the name `__union` or `__unionX`, where</div><div class="line"><a name="l03576"></a><span class="lineno"> 3576</span>&#160;`X` can be any name, or by an `$int` member to identify the member as a variant</div><div class="line"><a name="l03577"></a><span class="lineno"> 3577</span>&#160;selector tag:</div><div class="line"><a name="l03578"></a><span class="lineno"> 3578</span>&#160;</div><div class="line"><a name="l03579"></a><span class="lineno"> 3579</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03580"></a><span class="lineno"> 3580</span>&#160;    class ns__record</div><div class="line"><a name="l03581"></a><span class="lineno"> 3581</span>&#160;    {</div><div class="line"><a name="l03582"></a><span class="lineno"> 3582</span>&#160;     public:</div><div class="line"><a name="l03583"></a><span class="lineno"> 3583</span>&#160;      $ int  xORnORs;    // variant selector with values SOAP_UNION_fieldname</div><div class="line"><a name="l03584"></a><span class="lineno"> 3584</span>&#160;        union ns__choice</div><div class="line"><a name="l03585"></a><span class="lineno"> 3585</span>&#160;        {</div><div class="line"><a name="l03586"></a><span class="lineno"> 3586</span>&#160;            float x;</div><div class="line"><a name="l03587"></a><span class="lineno"> 3587</span>&#160;            int   n;</div><div class="line"><a name="l03588"></a><span class="lineno"> 3588</span>&#160;            char *s;</div><div class="line"><a name="l03589"></a><span class="lineno"> 3589</span>&#160;        } u;</div><div class="line"><a name="l03590"></a><span class="lineno"> 3590</span>&#160;        std::string name;</div><div class="line"><a name="l03591"></a><span class="lineno"> 3591</span>&#160;    };</div><div class="line"><a name="l03592"></a><span class="lineno"> 3592</span>&#160;~~~</div><div class="line"><a name="l03593"></a><span class="lineno"> 3593</span>&#160;</div><div class="line"><a name="l03594"></a><span class="lineno"> 3594</span>&#160;The variant selector values are auto-generated based on the union name `choice`</div><div class="line"><a name="l03595"></a><span class="lineno"> 3595</span>&#160;and the names of its members `x`, `n`, and `s`:</div><div class="line"><a name="l03596"></a><span class="lineno"> 3596</span>&#160;</div><div class="line"><a name="l03597"></a><span class="lineno"> 3597</span>&#160;- `xORnORs = SOAP_UNION_ns__choice_x` when `u.x` is valid.</div><div class="line"><a name="l03598"></a><span class="lineno"> 3598</span>&#160;</div><div class="line"><a name="l03599"></a><span class="lineno"> 3599</span>&#160;- `xORnORs = SOAP_UNION_ns__choice_n` when `u.n` is valid.</div><div class="line"><a name="l03600"></a><span class="lineno"> 3600</span>&#160;</div><div class="line"><a name="l03601"></a><span class="lineno"> 3601</span>&#160;- `xORnORs = SOAP_UNION_ns__choice_s` when `u.s` is valid.</div><div class="line"><a name="l03602"></a><span class="lineno"> 3602</span>&#160;</div><div class="line"><a name="l03603"></a><span class="lineno"> 3603</span>&#160;- `xORnORs = 0` when none are valid (should only be used with great care,</div><div class="line"><a name="l03604"></a><span class="lineno"> 3604</span>&#160;  because XSD validation may fail when content is required but absent).</div><div class="line"><a name="l03605"></a><span class="lineno"> 3605</span>&#160;</div><div class="line"><a name="l03606"></a><span class="lineno"> 3606</span>&#160;This class maps to a complexType with a sequence and choice in the</div><div class="line"><a name="l03607"></a><span class="lineno"> 3607</span>&#160;soapcpp2-generated XML schema:</div><div class="line"><a name="l03608"></a><span class="lineno"> 3608</span>&#160;</div><div class="line"><a name="l03609"></a><span class="lineno"> 3609</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03610"></a><span class="lineno"> 3610</span>&#160;~~~{.xml}</div><div class="line"><a name="l03611"></a><span class="lineno"> 3611</span>&#160;    &lt;complexType name=&quot;record&quot;&gt;</div><div class="line"><a name="l03612"></a><span class="lineno"> 3612</span>&#160;      &lt;sequence&gt;</div><div class="line"><a name="l03613"></a><span class="lineno"> 3613</span>&#160;        &lt;choice&gt;</div><div class="line"><a name="l03614"></a><span class="lineno"> 3614</span>&#160;          &lt;element name=&quot;x&quot; type=&quot;xsd:float&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03615"></a><span class="lineno"> 3615</span>&#160;          &lt;element name=&quot;n&quot; type=&quot;xsd:int&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03616"></a><span class="lineno"> 3616</span>&#160;          &lt;element name=&quot;s&quot; type=&quot;xsd:string&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot; nillable=&quot;true&quot;/&gt;</div><div class="line"><a name="l03617"></a><span class="lineno"> 3617</span>&#160;        &lt;/choice&gt;</div><div class="line"><a name="l03618"></a><span class="lineno"> 3618</span>&#160;        &lt;element name=&quot;names&quot; type=&quot;xsd:string&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot; nillable=&quot;true&quot;/&gt;</div><div class="line"><a name="l03619"></a><span class="lineno"> 3619</span>&#160;      &lt;/sequence&gt;</div><div class="line"><a name="l03620"></a><span class="lineno"> 3620</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l03621"></a><span class="lineno"> 3621</span>&#160;~~~</div><div class="line"><a name="l03622"></a><span class="lineno"> 3622</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03623"></a><span class="lineno"> 3623</span>&#160;</div><div class="line"><a name="l03624"></a><span class="lineno"> 3624</span>&#160;An STL container or dynamic array of a union requires wrapping the variant</div><div class="line"><a name="l03625"></a><span class="lineno"> 3625</span>&#160;selector and union member in a struct:</div><div class="line"><a name="l03626"></a><span class="lineno"> 3626</span>&#160;</div><div class="line"><a name="l03627"></a><span class="lineno"> 3627</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03628"></a><span class="lineno"> 3628</span>&#160;    class ns__record</div><div class="line"><a name="l03629"></a><span class="lineno"> 3629</span>&#160;    {</div><div class="line"><a name="l03630"></a><span class="lineno"> 3630</span>&#160;     public:</div><div class="line"><a name="l03631"></a><span class="lineno"> 3631</span>&#160;        std::vector&lt;</div><div class="line"><a name="l03632"></a><span class="lineno"> 3632</span>&#160;        struct ns__data  // data with a choice of x, n, or s</div><div class="line"><a name="l03633"></a><span class="lineno"> 3633</span>&#160;        {</div><div class="line"><a name="l03634"></a><span class="lineno"> 3634</span>&#160;          $ int  xORnORs; // variant selector with values SOAP_UNION_fieldname</div><div class="line"><a name="l03635"></a><span class="lineno"> 3635</span>&#160;            union ns__choice</div><div class="line"><a name="l03636"></a><span class="lineno"> 3636</span>&#160;            {</div><div class="line"><a name="l03637"></a><span class="lineno"> 3637</span>&#160;                float x;</div><div class="line"><a name="l03638"></a><span class="lineno"> 3638</span>&#160;                int   n;</div><div class="line"><a name="l03639"></a><span class="lineno"> 3639</span>&#160;                char *s;</div><div class="line"><a name="l03640"></a><span class="lineno"> 3640</span>&#160;            } u;</div><div class="line"><a name="l03641"></a><span class="lineno"> 3641</span>&#160;        }&gt; data;         // vector with data</div><div class="line"><a name="l03642"></a><span class="lineno"> 3642</span>&#160;    };</div><div class="line"><a name="l03643"></a><span class="lineno"> 3643</span>&#160;~~~</div><div class="line"><a name="l03644"></a><span class="lineno"> 3644</span>&#160;</div><div class="line"><a name="l03645"></a><span class="lineno"> 3645</span>&#160;and an equivalent definition with a dynamic array instead of a `std::vector`</div><div class="line"><a name="l03646"></a><span class="lineno"> 3646</span>&#160;(you can use this in C with structs):</div><div class="line"><a name="l03647"></a><span class="lineno"> 3647</span>&#160;</div><div class="line"><a name="l03648"></a><span class="lineno"> 3648</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03649"></a><span class="lineno"> 3649</span>&#160;    class ns__record</div><div class="line"><a name="l03650"></a><span class="lineno"> 3650</span>&#160;    {</div><div class="line"><a name="l03651"></a><span class="lineno"> 3651</span>&#160;     public:</div><div class="line"><a name="l03652"></a><span class="lineno"> 3652</span>&#160;      $ int  sizeOfdata; // size of dynamic array</div><div class="line"><a name="l03653"></a><span class="lineno"> 3653</span>&#160;        struct ns__data   // data with a choice of x, n, or s</div><div class="line"><a name="l03654"></a><span class="lineno"> 3654</span>&#160;        {</div><div class="line"><a name="l03655"></a><span class="lineno"> 3655</span>&#160;          $ int  xORnORs;  // variant selector with values SOAP_UNION_fieldname</div><div class="line"><a name="l03656"></a><span class="lineno"> 3656</span>&#160;            union ns__choice</div><div class="line"><a name="l03657"></a><span class="lineno"> 3657</span>&#160;            {</div><div class="line"><a name="l03658"></a><span class="lineno"> 3658</span>&#160;                float x;</div><div class="line"><a name="l03659"></a><span class="lineno"> 3659</span>&#160;                int   n;</div><div class="line"><a name="l03660"></a><span class="lineno"> 3660</span>&#160;                char *s;</div><div class="line"><a name="l03661"></a><span class="lineno"> 3661</span>&#160;            } u;</div><div class="line"><a name="l03662"></a><span class="lineno"> 3662</span>&#160;        } *data;          // points to the data array of length sizeOfdata</div><div class="line"><a name="l03663"></a><span class="lineno"> 3663</span>&#160;    };</div><div class="line"><a name="l03664"></a><span class="lineno"> 3664</span>&#160;~~~</div><div class="line"><a name="l03665"></a><span class="lineno"> 3665</span>&#160;</div><div class="line"><a name="l03666"></a><span class="lineno"> 3666</span>&#160;This maps to two complexTypes in the soapcpp2-generated XML schema:</div><div class="line"><a name="l03667"></a><span class="lineno"> 3667</span>&#160;</div><div class="line"><a name="l03668"></a><span class="lineno"> 3668</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03669"></a><span class="lineno"> 3669</span>&#160;~~~{.xml}</div><div class="line"><a name="l03670"></a><span class="lineno"> 3670</span>&#160;    &lt;complexType name=&quot;data&quot;&gt;</div><div class="line"><a name="l03671"></a><span class="lineno"> 3671</span>&#160;      &lt;choice&gt;</div><div class="line"><a name="l03672"></a><span class="lineno"> 3672</span>&#160;        &lt;element name=&quot;x&quot; type=&quot;xsd:float&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03673"></a><span class="lineno"> 3673</span>&#160;        &lt;element name=&quot;n&quot; type=&quot;xsd:int&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03674"></a><span class="lineno"> 3674</span>&#160;        &lt;element name=&quot;s&quot; type=&quot;xsd:string&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot; nillable=&quot;true&quot;/&gt;</div><div class="line"><a name="l03675"></a><span class="lineno"> 3675</span>&#160;      &lt;/choice&gt;</div><div class="line"><a name="l03676"></a><span class="lineno"> 3676</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l03677"></a><span class="lineno"> 3677</span>&#160;    &lt;complexType name=&quot;record&quot;&gt;</div><div class="line"><a name="l03678"></a><span class="lineno"> 3678</span>&#160;      &lt;sequence&gt;</div><div class="line"><a name="l03679"></a><span class="lineno"> 3679</span>&#160;        &lt;element name=&quot;data&quot; type=&quot;ns:data&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;unbounded&quot;/&gt;</div><div class="line"><a name="l03680"></a><span class="lineno"> 3680</span>&#160;      &lt;/sequence&gt;</div><div class="line"><a name="l03681"></a><span class="lineno"> 3681</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l03682"></a><span class="lineno"> 3682</span>&#160;~~~</div><div class="line"><a name="l03683"></a><span class="lineno"> 3683</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03684"></a><span class="lineno"> 3684</span>&#160;</div><div class="line"><a name="l03685"></a><span class="lineno"> 3685</span>&#160;The XML value space consists of a sequence of item elements each wrapped in an</div><div class="line"><a name="l03686"></a><span class="lineno"> 3686</span>&#160;data element:</div><div class="line"><a name="l03687"></a><span class="lineno"> 3687</span>&#160;</div><div class="line"><a name="l03688"></a><span class="lineno"> 3688</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03689"></a><span class="lineno"> 3689</span>&#160;~~~{.xml}</div><div class="line"><a name="l03690"></a><span class="lineno"> 3690</span>&#160;    &lt;ns:record xmlns:ns=&quot;urn:types&quot; ...&gt;</div><div class="line"><a name="l03691"></a><span class="lineno"> 3691</span>&#160;      &lt;data&gt;</div><div class="line"><a name="l03692"></a><span class="lineno"> 3692</span>&#160;        &lt;n&gt;123&lt;/n&gt;</div><div class="line"><a name="l03693"></a><span class="lineno"> 3693</span>&#160;      &lt;/data&gt;</div><div class="line"><a name="l03694"></a><span class="lineno"> 3694</span>&#160;      &lt;data&gt;</div><div class="line"><a name="l03695"></a><span class="lineno"> 3695</span>&#160;        &lt;x&gt;3.1&lt;/x&gt;</div><div class="line"><a name="l03696"></a><span class="lineno"> 3696</span>&#160;      &lt;/data&gt;</div><div class="line"><a name="l03697"></a><span class="lineno"> 3697</span>&#160;      &lt;data&gt;</div><div class="line"><a name="l03698"></a><span class="lineno"> 3698</span>&#160;        &lt;s&gt;hello&lt;/s&gt;</div><div class="line"><a name="l03699"></a><span class="lineno"> 3699</span>&#160;      &lt;/data&gt;</div><div class="line"><a name="l03700"></a><span class="lineno"> 3700</span>&#160;      &lt;data&gt;</div><div class="line"><a name="l03701"></a><span class="lineno"> 3701</span>&#160;        &lt;s&gt;world&lt;/s&gt;</div><div class="line"><a name="l03702"></a><span class="lineno"> 3702</span>&#160;      &lt;/data&gt;</div><div class="line"><a name="l03703"></a><span class="lineno"> 3703</span>&#160;    &lt;/ns:record&gt;</div><div class="line"><a name="l03704"></a><span class="lineno"> 3704</span>&#160;~~~</div><div class="line"><a name="l03705"></a><span class="lineno"> 3705</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03706"></a><span class="lineno"> 3706</span>&#160;</div><div class="line"><a name="l03707"></a><span class="lineno"> 3707</span>&#160;To remove the wrapping data element, simply rename the wrapping struct to</div><div class="line"><a name="l03708"></a><span class="lineno"> 3708</span>&#160;`__ns__data` and the member to `__data` to make this member invisible to the</div><div class="line"><a name="l03709"></a><span class="lineno"> 3709</span>&#160;serializer.  The double underscore prefix naming convention is used for the</div><div class="line"><a name="l03710"></a><span class="lineno"> 3710</span>&#160;struct name and member name.  Also use a dynamic array instead of a STL</div><div class="line"><a name="l03711"></a><span class="lineno"> 3711</span>&#160;container (so you can also use this approach in C with structs):</div><div class="line"><a name="l03712"></a><span class="lineno"> 3712</span>&#160;</div><div class="line"><a name="l03713"></a><span class="lineno"> 3713</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03714"></a><span class="lineno"> 3714</span>&#160;    class ns__record</div><div class="line"><a name="l03715"></a><span class="lineno"> 3715</span>&#160;    {</div><div class="line"><a name="l03716"></a><span class="lineno"> 3716</span>&#160;     public:</div><div class="line"><a name="l03717"></a><span class="lineno"> 3717</span>&#160;      $ int sizeOfdata;   // size of dynamic array</div><div class="line"><a name="l03718"></a><span class="lineno"> 3718</span>&#160;        struct __ns__data // contains choice of x, n, or s</div><div class="line"><a name="l03719"></a><span class="lineno"> 3719</span>&#160;        {</div><div class="line"><a name="l03720"></a><span class="lineno"> 3720</span>&#160;          $ int  xORnORs; // variant selector with values SOAP_UNION_fieldname</div><div class="line"><a name="l03721"></a><span class="lineno"> 3721</span>&#160;            union ns__choice</div><div class="line"><a name="l03722"></a><span class="lineno"> 3722</span>&#160;            {</div><div class="line"><a name="l03723"></a><span class="lineno"> 3723</span>&#160;                float x;</div><div class="line"><a name="l03724"></a><span class="lineno"> 3724</span>&#160;                int   n;</div><div class="line"><a name="l03725"></a><span class="lineno"> 3725</span>&#160;                char *s;</div><div class="line"><a name="l03726"></a><span class="lineno"> 3726</span>&#160;            } u;</div><div class="line"><a name="l03727"></a><span class="lineno"> 3727</span>&#160;        } *__data;        // points to the data array of length sizeOfdata</div><div class="line"><a name="l03728"></a><span class="lineno"> 3728</span>&#160;    };</div><div class="line"><a name="l03729"></a><span class="lineno"> 3729</span>&#160;~~~</div><div class="line"><a name="l03730"></a><span class="lineno"> 3730</span>&#160;</div><div class="line"><a name="l03731"></a><span class="lineno"> 3731</span>&#160;This maps to a complexType in the soapcpp2-generated XML schema:</div><div class="line"><a name="l03732"></a><span class="lineno"> 3732</span>&#160;</div><div class="line"><a name="l03733"></a><span class="lineno"> 3733</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03734"></a><span class="lineno"> 3734</span>&#160;~~~{.xml}</div><div class="line"><a name="l03735"></a><span class="lineno"> 3735</span>&#160;    &lt;complexType name=&quot;record&quot;&gt;</div><div class="line"><a name="l03736"></a><span class="lineno"> 3736</span>&#160;      &lt;sequence minOccurs=&quot;0&quot; maxOccurs=&quot;unbounded&quot;&gt;</div><div class="line"><a name="l03737"></a><span class="lineno"> 3737</span>&#160;        &lt;choice&gt;</div><div class="line"><a name="l03738"></a><span class="lineno"> 3738</span>&#160;          &lt;element name=&quot;x&quot; type=&quot;xsd:float&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03739"></a><span class="lineno"> 3739</span>&#160;          &lt;element name=&quot;n&quot; type=&quot;xsd:int&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03740"></a><span class="lineno"> 3740</span>&#160;          &lt;element name=&quot;s&quot; type=&quot;xsd:string&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot; nillable=&quot;true&quot;/&gt;</div><div class="line"><a name="l03741"></a><span class="lineno"> 3741</span>&#160;        &lt;/choice&gt;</div><div class="line"><a name="l03742"></a><span class="lineno"> 3742</span>&#160;      &lt;/sequence&gt;</div><div class="line"><a name="l03743"></a><span class="lineno"> 3743</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l03744"></a><span class="lineno"> 3744</span>&#160;~~~</div><div class="line"><a name="l03745"></a><span class="lineno"> 3745</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03746"></a><span class="lineno"> 3746</span>&#160;</div><div class="line"><a name="l03747"></a><span class="lineno"> 3747</span>&#160;The XML value space consists of a sequence of &lt;i&gt;`&lt;x&gt;`&lt;/i&gt;, &lt;i&gt;`&lt;n&gt;`&lt;/i&gt;, and/or &lt;i&gt;`&lt;s&gt;`&lt;/i&gt;</div><div class="line"><a name="l03748"></a><span class="lineno"> 3748</span>&#160;elements:</div><div class="line"><a name="l03749"></a><span class="lineno"> 3749</span>&#160;</div><div class="line"><a name="l03750"></a><span class="lineno"> 3750</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03751"></a><span class="lineno"> 3751</span>&#160;~~~{.xml}</div><div class="line"><a name="l03752"></a><span class="lineno"> 3752</span>&#160;    &lt;ns:record xmlns:ns=&quot;urn:types&quot; ...&gt;</div><div class="line"><a name="l03753"></a><span class="lineno"> 3753</span>&#160;      &lt;n&gt;123&lt;/n&gt;</div><div class="line"><a name="l03754"></a><span class="lineno"> 3754</span>&#160;      &lt;x&gt;3.1&lt;/x&gt;</div><div class="line"><a name="l03755"></a><span class="lineno"> 3755</span>&#160;      &lt;s&gt;hello&lt;/s&gt;</div><div class="line"><a name="l03756"></a><span class="lineno"> 3756</span>&#160;      &lt;s&gt;world&lt;/s&gt;</div><div class="line"><a name="l03757"></a><span class="lineno"> 3757</span>&#160;    &lt;/ns:record&gt;</div><div class="line"><a name="l03758"></a><span class="lineno"> 3758</span>&#160;~~~</div><div class="line"><a name="l03759"></a><span class="lineno"> 3759</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03760"></a><span class="lineno"> 3760</span>&#160;</div><div class="line"><a name="l03761"></a><span class="lineno"> 3761</span>&#160;Please note that structs, classes, and unions are unnested by soapcpp2 (as in</div><div class="line"><a name="l03762"></a><span class="lineno"> 3762</span>&#160;the C standard of nested structs and unions).  Therefore, the `ns__choice`</div><div class="line"><a name="l03763"></a><span class="lineno"> 3763</span>&#160;union in the `ns__record` class is redeclared at the top level despite its</div><div class="line"><a name="l03764"></a><span class="lineno"> 3764</span>&#160;nesting within the `ns__record` class.  This means that you will have to choose</div><div class="line"><a name="l03765"></a><span class="lineno"> 3765</span>&#160;a unique name for each nested struct, class, and union.</div><div class="line"><a name="l03766"></a><span class="lineno"> 3766</span>&#160;</div><div class="line"><a name="l03767"></a><span class="lineno"> 3767</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l03768"></a><span class="lineno"> 3768</span>&#160;</div><div class="line"><a name="l03769"></a><span class="lineno"> 3769</span>&#160;### Tagged void pointer members                                     {#toxsd9-12}</div><div class="line"><a name="l03770"></a><span class="lineno"> 3770</span>&#160;</div><div class="line"><a name="l03771"></a><span class="lineno"> 3771</span>&#160;To serialize data pointed to by `void*` requires run-time type information that</div><div class="line"><a name="l03772"></a><span class="lineno"> 3772</span>&#160;tells the serializer what type of data to serialize by means of a *tagged void</div><div class="line"><a name="l03773"></a><span class="lineno"> 3773</span>&#160;pointer*.  This type information is stored in a special type tag member of a</div><div class="line"><a name="l03774"></a><span class="lineno"> 3774</span>&#160;struct/class with the name `__type` or `__typeX`, where `X` can be any name, or</div><div class="line"><a name="l03775"></a><span class="lineno"> 3775</span>&#160;alternatively by an `$int` special member of any name as a type tag:</div><div class="line"><a name="l03776"></a><span class="lineno"> 3776</span>&#160;</div><div class="line"><a name="l03777"></a><span class="lineno"> 3777</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03778"></a><span class="lineno"> 3778</span>&#160;    class ns__record</div><div class="line"><a name="l03779"></a><span class="lineno"> 3779</span>&#160;    {</div><div class="line"><a name="l03780"></a><span class="lineno"> 3780</span>&#160;     public:</div><div class="line"><a name="l03781"></a><span class="lineno"> 3781</span>&#160;      $ int  typeOfdata; // type tag with values SOAP_TYPE_T</div><div class="line"><a name="l03782"></a><span class="lineno"> 3782</span>&#160;        void *data;      // points to some data of type T</div><div class="line"><a name="l03783"></a><span class="lineno"> 3783</span>&#160;    };</div><div class="line"><a name="l03784"></a><span class="lineno"> 3784</span>&#160;~~~</div><div class="line"><a name="l03785"></a><span class="lineno"> 3785</span>&#160;</div><div class="line"><a name="l03786"></a><span class="lineno"> 3786</span>&#160;A type tag member has nonzero values `SOAP_TYPE_T` where `T` is the name of a</div><div class="line"><a name="l03787"></a><span class="lineno"> 3787</span>&#160;struct/class or the name of a primitive type, such as `int`, `std__string` (for</div><div class="line"><a name="l03788"></a><span class="lineno"> 3788</span>&#160;`std::string`), `string` (for `char*`).</div><div class="line"><a name="l03789"></a><span class="lineno"> 3789</span>&#160;</div><div class="line"><a name="l03790"></a><span class="lineno"> 3790</span>&#160;This class maps to a complexType with a sequence in the soapcpp2-generated</div><div class="line"><a name="l03791"></a><span class="lineno"> 3791</span>&#160;XML schema:</div><div class="line"><a name="l03792"></a><span class="lineno"> 3792</span>&#160;</div><div class="line"><a name="l03793"></a><span class="lineno"> 3793</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03794"></a><span class="lineno"> 3794</span>&#160;~~~{.xml}</div><div class="line"><a name="l03795"></a><span class="lineno"> 3795</span>&#160;    &lt;complexType name=&quot;record&quot;&gt;</div><div class="line"><a name="l03796"></a><span class="lineno"> 3796</span>&#160;      &lt;sequence&gt;</div><div class="line"><a name="l03797"></a><span class="lineno"> 3797</span>&#160;        &lt;element name=&quot;data&quot; type=&quot;xsd:anyType&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03798"></a><span class="lineno"> 3798</span>&#160;      &lt;/sequence&gt;</div><div class="line"><a name="l03799"></a><span class="lineno"> 3799</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l03800"></a><span class="lineno"> 3800</span>&#160;~~~</div><div class="line"><a name="l03801"></a><span class="lineno"> 3801</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03802"></a><span class="lineno"> 3802</span>&#160;</div><div class="line"><a name="l03803"></a><span class="lineno"> 3803</span>&#160;The XML value space consists of the XML value space of the type with the</div><div class="line"><a name="l03804"></a><span class="lineno"> 3804</span>&#160;addition of an &lt;i&gt;`xsi:type`&lt;/i&gt; attribute to the enveloping element:</div><div class="line"><a name="l03805"></a><span class="lineno"> 3805</span>&#160;</div><div class="line"><a name="l03806"></a><span class="lineno"> 3806</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03807"></a><span class="lineno"> 3807</span>&#160;~~~{.xml}</div><div class="line"><a name="l03808"></a><span class="lineno"> 3808</span>&#160;    &lt;ns:record xmlns:ns=&quot;urn:types&quot; ...&gt;</div><div class="line"><a name="l03809"></a><span class="lineno"> 3809</span>&#160;      &lt;data xsi:type=&quot;xsd:int&quot;&gt;123&lt;/data&gt;</div><div class="line"><a name="l03810"></a><span class="lineno"> 3810</span>&#160;    &lt;/ns:record&gt;</div><div class="line"><a name="l03811"></a><span class="lineno"> 3811</span>&#160;~~~</div><div class="line"><a name="l03812"></a><span class="lineno"> 3812</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03813"></a><span class="lineno"> 3813</span>&#160;</div><div class="line"><a name="l03814"></a><span class="lineno"> 3814</span>&#160;This &lt;i&gt;`xsi:type`&lt;/i&gt; attribute is important for the receiving end to distinguish</div><div class="line"><a name="l03815"></a><span class="lineno"> 3815</span>&#160;the type of data to instantiate.  The receiver cannot deserialize the data</div><div class="line"><a name="l03816"></a><span class="lineno"> 3816</span>&#160;without an &lt;i&gt;`xsd:type`&lt;/i&gt; attribute.</div><div class="line"><a name="l03817"></a><span class="lineno"> 3817</span>&#160;</div><div class="line"><a name="l03818"></a><span class="lineno"> 3818</span>&#160;You can find the `SOAP_TYPE_T` name of each serializable type in the</div><div class="line"><a name="l03819"></a><span class="lineno"> 3819</span>&#160;auto-generated &lt;i&gt;`soapStub.h`&lt;/i&gt; file.</div><div class="line"><a name="l03820"></a><span class="lineno"> 3820</span>&#160;</div><div class="line"><a name="l03821"></a><span class="lineno"> 3821</span>&#160;Also all serializable C++ classes have a virtual `int T::soap_type()` member</div><div class="line"><a name="l03822"></a><span class="lineno"> 3822</span>&#160;that returns their `SOAP_TYPE_T` value that you can use.</div><div class="line"><a name="l03823"></a><span class="lineno"> 3823</span>&#160;</div><div class="line"><a name="l03824"></a><span class="lineno"> 3824</span>&#160;When the `void*` pointer is NULL or when `typeOfdata` is zero, the data is not</div><div class="line"><a name="l03825"></a><span class="lineno"> 3825</span>&#160;serialized.</div><div class="line"><a name="l03826"></a><span class="lineno"> 3826</span>&#160;</div><div class="line"><a name="l03827"></a><span class="lineno"> 3827</span>&#160;An STL container or dynamic array of `void*` pointers to &lt;i&gt;`xsd:anyType`&lt;/i&gt; data</div><div class="line"><a name="l03828"></a><span class="lineno"> 3828</span>&#160;requires wrapping the type tag and `void*` members in a struct:</div><div class="line"><a name="l03829"></a><span class="lineno"> 3829</span>&#160;</div><div class="line"><a name="l03830"></a><span class="lineno"> 3830</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03831"></a><span class="lineno"> 3831</span>&#160;    class ns__record</div><div class="line"><a name="l03832"></a><span class="lineno"> 3832</span>&#160;    {</div><div class="line"><a name="l03833"></a><span class="lineno"> 3833</span>&#160;     public:</div><div class="line"><a name="l03834"></a><span class="lineno"> 3834</span>&#160;        std::vector&lt;</div><div class="line"><a name="l03835"></a><span class="lineno"> 3835</span>&#160;        struct ns__data      // data with an xsd:anyType item</div><div class="line"><a name="l03836"></a><span class="lineno"> 3836</span>&#160;        {</div><div class="line"><a name="l03837"></a><span class="lineno"> 3837</span>&#160;          $ int  typeOfitem; // type tag with values SOAP_TYPE_T</div><div class="line"><a name="l03838"></a><span class="lineno"> 3838</span>&#160;            void *item;      // points to some item of type T</div><div class="line"><a name="l03839"></a><span class="lineno"> 3839</span>&#160;        }&gt; data;             // vector with data</div><div class="line"><a name="l03840"></a><span class="lineno"> 3840</span>&#160;    };</div><div class="line"><a name="l03841"></a><span class="lineno"> 3841</span>&#160;~~~</div><div class="line"><a name="l03842"></a><span class="lineno"> 3842</span>&#160;</div><div class="line"><a name="l03843"></a><span class="lineno"> 3843</span>&#160;and an equivalent definition with a dynamic array instead of a `std::vector`</div><div class="line"><a name="l03844"></a><span class="lineno"> 3844</span>&#160;(you can use this in C with structs):</div><div class="line"><a name="l03845"></a><span class="lineno"> 3845</span>&#160;</div><div class="line"><a name="l03846"></a><span class="lineno"> 3846</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03847"></a><span class="lineno"> 3847</span>&#160;    class ns__record</div><div class="line"><a name="l03848"></a><span class="lineno"> 3848</span>&#160;    {</div><div class="line"><a name="l03849"></a><span class="lineno"> 3849</span>&#160;     public:</div><div class="line"><a name="l03850"></a><span class="lineno"> 3850</span>&#160;      $ int sizeOfdata;      // size of dynamic array</div><div class="line"><a name="l03851"></a><span class="lineno"> 3851</span>&#160;        struct ns__data      // data with an xsd:anyType item</div><div class="line"><a name="l03852"></a><span class="lineno"> 3852</span>&#160;        {</div><div class="line"><a name="l03853"></a><span class="lineno"> 3853</span>&#160;          $ int  typeOfitem; // type tag with values SOAP_TYPE_T</div><div class="line"><a name="l03854"></a><span class="lineno"> 3854</span>&#160;            void *item;      // points to some item of type T</div><div class="line"><a name="l03855"></a><span class="lineno"> 3855</span>&#160;        } *data;             // points to the data array of length sizeOfdata</div><div class="line"><a name="l03856"></a><span class="lineno"> 3856</span>&#160;    };</div><div class="line"><a name="l03857"></a><span class="lineno"> 3857</span>&#160;~~~</div><div class="line"><a name="l03858"></a><span class="lineno"> 3858</span>&#160;</div><div class="line"><a name="l03859"></a><span class="lineno"> 3859</span>&#160;This maps to two complexTypes in the soapcpp2-generated XML schema:</div><div class="line"><a name="l03860"></a><span class="lineno"> 3860</span>&#160;</div><div class="line"><a name="l03861"></a><span class="lineno"> 3861</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03862"></a><span class="lineno"> 3862</span>&#160;~~~{.xml}</div><div class="line"><a name="l03863"></a><span class="lineno"> 3863</span>&#160;    &lt;complexType name=&quot;data&quot;&gt;</div><div class="line"><a name="l03864"></a><span class="lineno"> 3864</span>&#160;      &lt;sequence&gt;</div><div class="line"><a name="l03865"></a><span class="lineno"> 3865</span>&#160;        &lt;element name=&quot;item&quot; type=&quot;xsd:anyType&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot; nillable=&quot;true&quot;/&gt;</div><div class="line"><a name="l03866"></a><span class="lineno"> 3866</span>&#160;      &lt;/sequence&gt;</div><div class="line"><a name="l03867"></a><span class="lineno"> 3867</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l03868"></a><span class="lineno"> 3868</span>&#160;    &lt;complexType name=&quot;record&quot;&gt;</div><div class="line"><a name="l03869"></a><span class="lineno"> 3869</span>&#160;      &lt;sequence&gt;</div><div class="line"><a name="l03870"></a><span class="lineno"> 3870</span>&#160;        &lt;element name=&quot;data&quot; type=&quot;ns:data&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;unbounded&quot;/&gt;</div><div class="line"><a name="l03871"></a><span class="lineno"> 3871</span>&#160;      &lt;/sequence&gt;</div><div class="line"><a name="l03872"></a><span class="lineno"> 3872</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l03873"></a><span class="lineno"> 3873</span>&#160;~~~</div><div class="line"><a name="l03874"></a><span class="lineno"> 3874</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03875"></a><span class="lineno"> 3875</span>&#160;</div><div class="line"><a name="l03876"></a><span class="lineno"> 3876</span>&#160;The XML value space consists of a sequence of item elements each wrapped in a</div><div class="line"><a name="l03877"></a><span class="lineno"> 3877</span>&#160;data element:</div><div class="line"><a name="l03878"></a><span class="lineno"> 3878</span>&#160;</div><div class="line"><a name="l03879"></a><span class="lineno"> 3879</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03880"></a><span class="lineno"> 3880</span>&#160;~~~{.xml}</div><div class="line"><a name="l03881"></a><span class="lineno"> 3881</span>&#160;    &lt;ns:record xmlns:ns=&quot;urn:types&quot; ...&gt;</div><div class="line"><a name="l03882"></a><span class="lineno"> 3882</span>&#160;      &lt;data&gt;</div><div class="line"><a name="l03883"></a><span class="lineno"> 3883</span>&#160;        &lt;item xsi:type=&quot;xsd:int&quot;&gt;123&lt;/item&gt;</div><div class="line"><a name="l03884"></a><span class="lineno"> 3884</span>&#160;      &lt;/data&gt;</div><div class="line"><a name="l03885"></a><span class="lineno"> 3885</span>&#160;      &lt;data&gt;</div><div class="line"><a name="l03886"></a><span class="lineno"> 3886</span>&#160;        &lt;item xsi:type=&quot;xsd:double&quot;&gt;3.1&lt;/item&gt;</div><div class="line"><a name="l03887"></a><span class="lineno"> 3887</span>&#160;      &lt;/data&gt;</div><div class="line"><a name="l03888"></a><span class="lineno"> 3888</span>&#160;      &lt;data&gt;</div><div class="line"><a name="l03889"></a><span class="lineno"> 3889</span>&#160;        &lt;item xsi:type=&quot;xsd:string&quot;&gt;abc&lt;/item&gt;</div><div class="line"><a name="l03890"></a><span class="lineno"> 3890</span>&#160;      &lt;/data&gt;</div><div class="line"><a name="l03891"></a><span class="lineno"> 3891</span>&#160;    &lt;/ns:record&gt;</div><div class="line"><a name="l03892"></a><span class="lineno"> 3892</span>&#160;~~~</div><div class="line"><a name="l03893"></a><span class="lineno"> 3893</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03894"></a><span class="lineno"> 3894</span>&#160;</div><div class="line"><a name="l03895"></a><span class="lineno"> 3895</span>&#160;To remove the wrapping data elements, simply rename the wrapping struct and</div><div class="line"><a name="l03896"></a><span class="lineno"> 3896</span>&#160;member to `__data` to make this member invisible to the serializer with the</div><div class="line"><a name="l03897"></a><span class="lineno"> 3897</span>&#160;double underscore prefix naming convention.  Also use a dynamic array instead</div><div class="line"><a name="l03898"></a><span class="lineno"> 3898</span>&#160;of a STL container (you can use this in C with structs):</div><div class="line"><a name="l03899"></a><span class="lineno"> 3899</span>&#160;</div><div class="line"><a name="l03900"></a><span class="lineno"> 3900</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03901"></a><span class="lineno"> 3901</span>&#160;    class ns__record</div><div class="line"><a name="l03902"></a><span class="lineno"> 3902</span>&#160;    {</div><div class="line"><a name="l03903"></a><span class="lineno"> 3903</span>&#160;     public:</div><div class="line"><a name="l03904"></a><span class="lineno"> 3904</span>&#160;      $ int sizeOfdata;      // size of dynamic array</div><div class="line"><a name="l03905"></a><span class="lineno"> 3905</span>&#160;        struct __data        // contains xsd:anyType item</div><div class="line"><a name="l03906"></a><span class="lineno"> 3906</span>&#160;        {</div><div class="line"><a name="l03907"></a><span class="lineno"> 3907</span>&#160;          $ int typeOfitem;  // type tag with values SOAP_TYPE_T</div><div class="line"><a name="l03908"></a><span class="lineno"> 3908</span>&#160;            void *item;      // points to some item of type T</div><div class="line"><a name="l03909"></a><span class="lineno"> 3909</span>&#160;        } *__data;           // points to the data array of length sizeOfdata</div><div class="line"><a name="l03910"></a><span class="lineno"> 3910</span>&#160;    };</div><div class="line"><a name="l03911"></a><span class="lineno"> 3911</span>&#160;~~~</div><div class="line"><a name="l03912"></a><span class="lineno"> 3912</span>&#160;</div><div class="line"><a name="l03913"></a><span class="lineno"> 3913</span>&#160;This maps to a complexType in the soapcpp2-generated XML schema:</div><div class="line"><a name="l03914"></a><span class="lineno"> 3914</span>&#160;</div><div class="line"><a name="l03915"></a><span class="lineno"> 3915</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03916"></a><span class="lineno"> 3916</span>&#160;~~~{.xml}</div><div class="line"><a name="l03917"></a><span class="lineno"> 3917</span>&#160;    &lt;complexType name=&quot;record&quot;&gt;</div><div class="line"><a name="l03918"></a><span class="lineno"> 3918</span>&#160;      &lt;sequence minOccurs=&quot;0&quot; maxOccurs=&quot;unbounded&quot;&gt;</div><div class="line"><a name="l03919"></a><span class="lineno"> 3919</span>&#160;        &lt;element name=&quot;item&quot; type=&quot;xsd:anyType&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;</div><div class="line"><a name="l03920"></a><span class="lineno"> 3920</span>&#160;      &lt;/sequence&gt;</div><div class="line"><a name="l03921"></a><span class="lineno"> 3921</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l03922"></a><span class="lineno"> 3922</span>&#160;~~~</div><div class="line"><a name="l03923"></a><span class="lineno"> 3923</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03924"></a><span class="lineno"> 3924</span>&#160;</div><div class="line"><a name="l03925"></a><span class="lineno"> 3925</span>&#160;The XML value space consists of a sequence of data elements:</div><div class="line"><a name="l03926"></a><span class="lineno"> 3926</span>&#160;</div><div class="line"><a name="l03927"></a><span class="lineno"> 3927</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l03928"></a><span class="lineno"> 3928</span>&#160;~~~{.xml}</div><div class="line"><a name="l03929"></a><span class="lineno"> 3929</span>&#160;    &lt;ns:record xmlns:ns=&quot;urn:types&quot; ...&gt;</div><div class="line"><a name="l03930"></a><span class="lineno"> 3930</span>&#160;      &lt;item xsi:type=&quot;xsd:int&quot;&gt;123&lt;/item&gt;</div><div class="line"><a name="l03931"></a><span class="lineno"> 3931</span>&#160;      &lt;item xsi:type=&quot;xsd:double&quot;&gt;3.1&lt;/item&gt;</div><div class="line"><a name="l03932"></a><span class="lineno"> 3932</span>&#160;      &lt;item xsi:type=&quot;xsd:string&quot;&gt;abc&lt;/item&gt;</div><div class="line"><a name="l03933"></a><span class="lineno"> 3933</span>&#160;    &lt;/ns:record&gt;</div><div class="line"><a name="l03934"></a><span class="lineno"> 3934</span>&#160;~~~</div><div class="line"><a name="l03935"></a><span class="lineno"> 3935</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l03936"></a><span class="lineno"> 3936</span>&#160;</div><div class="line"><a name="l03937"></a><span class="lineno"> 3937</span>&#160;Again, please note that structs, classes, and unions are unnested by soapcpp2</div><div class="line"><a name="l03938"></a><span class="lineno"> 3938</span>&#160;(as in the C standard of nested structs and unions).  Therefore, the `__data`</div><div class="line"><a name="l03939"></a><span class="lineno"> 3939</span>&#160;struct in the `ns__record` class is redeclared at the top level despite its</div><div class="line"><a name="l03940"></a><span class="lineno"> 3940</span>&#160;nesting within the `ns__record` class.  This means that you will have to choose</div><div class="line"><a name="l03941"></a><span class="lineno"> 3941</span>&#160;a unique name for each nested struct, class, and union.</div><div class="line"><a name="l03942"></a><span class="lineno"> 3942</span>&#160;</div><div class="line"><a name="l03943"></a><span class="lineno"> 3943</span>&#160;@see Section [XSD type bindings](#typemap2).</div><div class="line"><a name="l03944"></a><span class="lineno"> 3944</span>&#160;</div><div class="line"><a name="l03945"></a><span class="lineno"> 3945</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l03946"></a><span class="lineno"> 3946</span>&#160;</div><div class="line"><a name="l03947"></a><span class="lineno"> 3947</span>&#160;### Adding get and set methods                                      {#toxsd9-13}</div><div class="line"><a name="l03948"></a><span class="lineno"> 3948</span>&#160;</div><div class="line"><a name="l03949"></a><span class="lineno"> 3949</span>&#160;A public `get` method may be added to a class or struct, which will be</div><div class="line"><a name="l03950"></a><span class="lineno"> 3950</span>&#160;triggered by the deserializer.  This method will be invoked right after the</div><div class="line"><a name="l03951"></a><span class="lineno"> 3951</span>&#160;instance is populated by the deserializer.  The `get` method can be used to</div><div class="line"><a name="l03952"></a><span class="lineno"> 3952</span>&#160;update or verify deserialized content.  It should return `SOAP_OK` or set</div><div class="line"><a name="l03953"></a><span class="lineno"> 3953</span>&#160;`soap::error` to a nonzero error code and return it.</div><div class="line"><a name="l03954"></a><span class="lineno"> 3954</span>&#160;</div><div class="line"><a name="l03955"></a><span class="lineno"> 3955</span>&#160;A public `set` method may be added to a class or struct, which will be</div><div class="line"><a name="l03956"></a><span class="lineno"> 3956</span>&#160;triggered by the serializer.  The method will be invoked just before the</div><div class="line"><a name="l03957"></a><span class="lineno"> 3957</span>&#160;instance is serialized.  Likewise, the `set` method should return `SOAP_OK` or</div><div class="line"><a name="l03958"></a><span class="lineno"> 3958</span>&#160;set set `soap::error` to a nonzero error code and return it.</div><div class="line"><a name="l03959"></a><span class="lineno"> 3959</span>&#160;</div><div class="line"><a name="l03960"></a><span class="lineno"> 3960</span>&#160;For example, adding a `set` and `get` method to a class declaration:</div><div class="line"><a name="l03961"></a><span class="lineno"> 3961</span>&#160;</div><div class="line"><a name="l03962"></a><span class="lineno"> 3962</span>&#160;~~~{.cpp}</div><div class="line"><a name="l03963"></a><span class="lineno"> 3963</span>&#160;    class ns__record</div><div class="line"><a name="l03964"></a><span class="lineno"> 3964</span>&#160;    {</div><div class="line"><a name="l03965"></a><span class="lineno"> 3965</span>&#160;     public:</div><div class="line"><a name="l03966"></a><span class="lineno"> 3966</span>&#160;        int set(struct soap*); // triggered before serialization</div><div class="line"><a name="l03967"></a><span class="lineno"> 3967</span>&#160;        int get(struct soap*); // triggered after deserialization</div><div class="line"><a name="l03968"></a><span class="lineno"> 3968</span>&#160;        ...</div><div class="line"><a name="l03969"></a><span class="lineno"> 3969</span>&#160;    };</div><div class="line"><a name="l03970"></a><span class="lineno"> 3970</span>&#160;~~~</div><div class="line"><a name="l03971"></a><span class="lineno"> 3971</span>&#160;</div><div class="line"><a name="l03972"></a><span class="lineno"> 3972</span>&#160;To add these and othe rmethods to classes and structs with wsdl2h and</div><div class="line"><a name="l03973"></a><span class="lineno"> 3973</span>&#160;&lt;i&gt;`typemap.dat`&lt;/i&gt;, please see [class/struct member additions](#typemap3).</div><div class="line"><a name="l03974"></a><span class="lineno"> 3974</span>&#160;</div><div class="line"><a name="l03975"></a><span class="lineno"> 3975</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l03976"></a><span class="lineno"> 3976</span>&#160;</div><div class="line"><a name="l03977"></a><span class="lineno"> 3977</span>&#160;### Operations on classes and structs                               {#toxsd9-14}</div><div class="line"><a name="l03978"></a><span class="lineno"> 3978</span>&#160;</div><div class="line"><a name="l03979"></a><span class="lineno"> 3979</span>&#160;The following functions/macros are generated by soapcpp2 for each type `T`,</div><div class="line"><a name="l03980"></a><span class="lineno"> 3980</span>&#160;which should make it easier to send, receive, and copy XML data in C and in</div><div class="line"><a name="l03981"></a><span class="lineno"> 3981</span>&#160;C++:</div><div class="line"><a name="l03982"></a><span class="lineno"> 3982</span>&#160;</div><div class="line"><a name="l03983"></a><span class="lineno"> 3983</span>&#160;- `int soap_write_T(struct soap*, T*)` writes an instance of `T` to a file via</div><div class="line"><a name="l03984"></a><span class="lineno"> 3984</span>&#160;   file descriptor `int soap::sendfd)` or to a stream via `std::ostream</div><div class="line"><a name="l03985"></a><span class="lineno"> 3985</span>&#160;   *soap::os` (C++ only) or saves into a NUL-terminated string by setting</div><div class="line"><a name="l03986"></a><span class="lineno"> 3986</span>&#160;   `const char **soap::os` to a string pointer to be set (C only).  Returns</div><div class="line"><a name="l03987"></a><span class="lineno"> 3987</span>&#160;   `SOAP_OK` on success or an error code, also stored in `soap::error`.</div><div class="line"><a name="l03988"></a><span class="lineno"> 3988</span>&#160;</div><div class="line"><a name="l03989"></a><span class="lineno"> 3989</span>&#160;- `int soap_read_T(struct soap*, T*)` reads an instance of `T` from a file via</div><div class="line"><a name="l03990"></a><span class="lineno"> 3990</span>&#160;   file descriptor `int soap::recvfd)` or from a stream via `std::istream</div><div class="line"><a name="l03991"></a><span class="lineno"> 3991</span>&#160;   *soap::is` (C++ only) or reads from a NUL-termianted string `const char</div><div class="line"><a name="l03992"></a><span class="lineno"> 3992</span>&#160;   *soap::is` (C only).  Returns `SOAP_OK` on success or an error code, also</div><div class="line"><a name="l03993"></a><span class="lineno"> 3993</span>&#160;   stored in `soap::error`.</div><div class="line"><a name="l03994"></a><span class="lineno"> 3994</span>&#160;</div><div class="line"><a name="l03995"></a><span class="lineno"> 3995</span>&#160;- `void soap_default_T(struct soap*, T*)` sets an instance `T` to its default</div><div class="line"><a name="l03996"></a><span class="lineno"> 3996</span>&#160;  value, resetting members of a struct to their initial values (for classes we</div><div class="line"><a name="l03997"></a><span class="lineno"> 3997</span>&#160;  use method `T::soap_default`, see below).  If `T` is a struct that has a</div><div class="line"><a name="l03998"></a><span class="lineno"> 3998</span>&#160;  `soap` pointer member to a `::soap` context then this pointer member will be</div><div class="line"><a name="l03999"></a><span class="lineno"> 3999</span>&#160;  set to the first argument passed to this function to initialize its `soap`</div><div class="line"><a name="l04000"></a><span class="lineno"> 4000</span>&#160;  pointer member.</div><div class="line"><a name="l04001"></a><span class="lineno"> 4001</span>&#160;</div><div class="line"><a name="l04002"></a><span class="lineno"> 4002</span>&#160;- `T * soap_dup_T(struct soap*, T *dst, const T *src)` (requires &lt;b&gt;`soapcpp2 -Ec`&lt;/b&gt;)</div><div class="line"><a name="l04003"></a><span class="lineno"> 4003</span>&#160;  deep copy `src` into `dst`, replicating all deep cycles and shared pointers</div><div class="line"><a name="l04004"></a><span class="lineno"> 4004</span>&#160;  when a managing `soap` context is provided as argument.  When `dst` is NULL,</div><div class="line"><a name="l04005"></a><span class="lineno"> 4005</span>&#160;  allocates space for `dst` and returns a pointer to the allocated copy.  Deep</div><div class="line"><a name="l04006"></a><span class="lineno"> 4006</span>&#160;  copy results in a tree when the `soap` context is NULL, but the presence of</div><div class="line"><a name="l04007"></a><span class="lineno"> 4007</span>&#160;  deep cycles will lead to non-termination.  Use flag `SOAP_XML_TREE` with</div><div class="line"><a name="l04008"></a><span class="lineno"> 4008</span>&#160;  managing context to copy into a tree without cycles and pointers to shared</div><div class="line"><a name="l04009"></a><span class="lineno"> 4009</span>&#160;  objects.  Returns `dst` or allocated copy when `dst` is NULL.</div><div class="line"><a name="l04010"></a><span class="lineno"> 4010</span>&#160;</div><div class="line"><a name="l04011"></a><span class="lineno"> 4011</span>&#160;- `void soap_del_T(const T*)` (requires &lt;b&gt;`soapcpp2 -Ed`&lt;/b&gt;) deletes all</div><div class="line"><a name="l04012"></a><span class="lineno"> 4012</span>&#160;  heap-allocated members of this object by deep deletion ONLY IF this object</div><div class="line"><a name="l04013"></a><span class="lineno"> 4013</span>&#160;  and all of its (deep) members are not managed by a `soap` context AND the deep</div><div class="line"><a name="l04014"></a><span class="lineno"> 4014</span>&#160;  structure is a tree (no cycles and co-referenced objects by way of multiple</div><div class="line"><a name="l04015"></a><span class="lineno"> 4015</span>&#160;  (non-smart) pointers pointing to the same data).  Can be safely used after</div><div class="line"><a name="l04016"></a><span class="lineno"> 4016</span>&#160;  `T * soap_dup_T(NULL, NULL, const T*)` to delete the deep copy returned.</div><div class="line"><a name="l04017"></a><span class="lineno"> 4017</span>&#160;  Does not delete the object itself.</div><div class="line"><a name="l04018"></a><span class="lineno"> 4018</span>&#160;</div><div class="line"><a name="l04019"></a><span class="lineno"> 4019</span>&#160;When in C++ mode, soapcpp2 tool adds several methods to classes in addition to</div><div class="line"><a name="l04020"></a><span class="lineno"> 4020</span>&#160;adding a default constructor and destructor (when these were not explicitly</div><div class="line"><a name="l04021"></a><span class="lineno"> 4021</span>&#160;declared).</div><div class="line"><a name="l04022"></a><span class="lineno"> 4022</span>&#160;</div><div class="line"><a name="l04023"></a><span class="lineno"> 4023</span>&#160;The public methods added to a class `T`:</div><div class="line"><a name="l04024"></a><span class="lineno"> 4024</span>&#160;</div><div class="line"><a name="l04025"></a><span class="lineno"> 4025</span>&#160;- `virtual int T::soap_type(void)` returns a unique type ID (`SOAP_TYPE_T`).</div><div class="line"><a name="l04026"></a><span class="lineno"> 4026</span>&#160;  This numeric ID can be used to distinguish base from derived instances.</div><div class="line"><a name="l04027"></a><span class="lineno"> 4027</span>&#160;</div><div class="line"><a name="l04028"></a><span class="lineno"> 4028</span>&#160;- `virtual void T::soap_default(struct soap*)` sets all data members to</div><div class="line"><a name="l04029"></a><span class="lineno"> 4029</span>&#160;  default values.  If class `T` has a `soap` pointer member to a `::soap`</div><div class="line"><a name="l04030"></a><span class="lineno"> 4030</span>&#160;  context then this pointer member will be set to the argument passed to this</div><div class="line"><a name="l04031"></a><span class="lineno"> 4031</span>&#160;  function to initialize its `soap` pointer member.</div><div class="line"><a name="l04032"></a><span class="lineno"> 4032</span>&#160;</div><div class="line"><a name="l04033"></a><span class="lineno"> 4033</span>&#160;- `virtual void T::soap_serialize(struct soap*) const` serializes object to</div><div class="line"><a name="l04034"></a><span class="lineno"> 4034</span>&#160;  prepare for SOAP 1.1/1.2 encoded output (or with `SOAP_XML_GRAPH`) by</div><div class="line"><a name="l04035"></a><span class="lineno"> 4035</span>&#160;  analyzing its (cyclic) structures.</div><div class="line"><a name="l04036"></a><span class="lineno"> 4036</span>&#160;</div><div class="line"><a name="l04037"></a><span class="lineno"> 4037</span>&#160;- `virtual int T::soap_put(struct soap*, const char *tag, const char *type) const`</div><div class="line"><a name="l04038"></a><span class="lineno"> 4038</span>&#160;  emits object in XML, compliant with SOAP 1.1 encoding style, return error</div><div class="line"><a name="l04039"></a><span class="lineno"> 4039</span>&#160;  code or `SOAP_OK`.  Requires `soap_begin_send(soap)` and</div><div class="line"><a name="l04040"></a><span class="lineno"> 4040</span>&#160;  `soap_end_send(soap)`.</div><div class="line"><a name="l04041"></a><span class="lineno"> 4041</span>&#160;</div><div class="line"><a name="l04042"></a><span class="lineno"> 4042</span>&#160;- `virtual int T::soap_out(struct soap*, const char *tag, int id, const char *type) const`</div><div class="line"><a name="l04043"></a><span class="lineno"> 4043</span>&#160;  emits object in XML, with tag and optional id attribute and &lt;i&gt;`xsi:type`&lt;/i&gt;,</div><div class="line"><a name="l04044"></a><span class="lineno"> 4044</span>&#160;  return error code or `SOAP_OK`.  Requires `soap_begin_send(soap)` and</div><div class="line"><a name="l04045"></a><span class="lineno"> 4045</span>&#160;  `soap_end_send(soap)`.</div><div class="line"><a name="l04046"></a><span class="lineno"> 4046</span>&#160;</div><div class="line"><a name="l04047"></a><span class="lineno"> 4047</span>&#160;- `virtual void * T::soap_get(struct soap*, const char *tag, const char *type)`</div><div class="line"><a name="l04048"></a><span class="lineno"> 4048</span>&#160;  Get object from XML, compliant with SOAP 1.1 encoding style, return pointer</div><div class="line"><a name="l04049"></a><span class="lineno"> 4049</span>&#160;  to object or NULL on error.  Requires `soap_begin_recv(soap)` and</div><div class="line"><a name="l04050"></a><span class="lineno"> 4050</span>&#160;  `soap_end_recv(soap)`.</div><div class="line"><a name="l04051"></a><span class="lineno"> 4051</span>&#160;</div><div class="line"><a name="l04052"></a><span class="lineno"> 4052</span>&#160;- `virtual void *soap_in(struct soap*, const char *tag, const char *type)`</div><div class="line"><a name="l04053"></a><span class="lineno"> 4053</span>&#160;  Get object from XML, with matching tag and type (NULL matches any tag and</div><div class="line"><a name="l04054"></a><span class="lineno"> 4054</span>&#160;  type), return pointer to object or NULL on error.  Requires</div><div class="line"><a name="l04055"></a><span class="lineno"> 4055</span>&#160;  `soap_begin_recv(soap)` and `soap_end_recv(soap)`</div><div class="line"><a name="l04056"></a><span class="lineno"> 4056</span>&#160;</div><div class="line"><a name="l04057"></a><span class="lineno"> 4057</span>&#160;- `virtual T * T::soap_alloc(void) const` returns a new object of type `T`,</div><div class="line"><a name="l04058"></a><span class="lineno"> 4058</span>&#160;  default initialized and not managed by a `soap` context.</div><div class="line"><a name="l04059"></a><span class="lineno"> 4059</span>&#160;</div><div class="line"><a name="l04060"></a><span class="lineno"> 4060</span>&#160;- `virtual T * T::soap_dup(struct soap*) const` (requires &lt;b&gt;`soapcpp2 -Ec`&lt;/b&gt;)</div><div class="line"><a name="l04061"></a><span class="lineno"> 4061</span>&#160;  returns a duplicate of this object by deep copying, replicating all deep</div><div class="line"><a name="l04062"></a><span class="lineno"> 4062</span>&#160;  cycles and shared pointers when a managing `soap` context is provided as</div><div class="line"><a name="l04063"></a><span class="lineno"> 4063</span>&#160;  argument.  Deep copy is a tree when argument is NULL, but the presence of</div><div class="line"><a name="l04064"></a><span class="lineno"> 4064</span>&#160;  deep cycles will lead to non-termination.  Use flag `SOAP_XML_TREE` with the</div><div class="line"><a name="l04065"></a><span class="lineno"> 4065</span>&#160;  managing context to copy into a tree without cycles and pointers to shared</div><div class="line"><a name="l04066"></a><span class="lineno"> 4066</span>&#160;  objects.</div><div class="line"><a name="l04067"></a><span class="lineno"> 4067</span>&#160;</div><div class="line"><a name="l04068"></a><span class="lineno"> 4068</span>&#160;- `virtual void T::soap_del() const` (rquires &lt;b&gt;`soapcpp2 -Ed`&lt;/b&gt;) deletes all</div><div class="line"><a name="l04069"></a><span class="lineno"> 4069</span>&#160;  heap-allocated members of this object by deep deletion ONLY IF this object</div><div class="line"><a name="l04070"></a><span class="lineno"> 4070</span>&#160;  and all of its (deep) members are not managed by a `soap` context AND the deep</div><div class="line"><a name="l04071"></a><span class="lineno"> 4071</span>&#160;  structure is a tree (no cycles and co-referenced objects by way of multiple</div><div class="line"><a name="l04072"></a><span class="lineno"> 4072</span>&#160;  (non-smart) pointers pointing to the same data).  Can be safely used after</div><div class="line"><a name="l04073"></a><span class="lineno"> 4073</span>&#160;  `soap_dup(NULL)` to delete the deep copy.  Does not delete the object itself.</div><div class="line"><a name="l04074"></a><span class="lineno"> 4074</span>&#160;</div><div class="line"><a name="l04075"></a><span class="lineno"> 4075</span>&#160;Also, there are four variations of `soap_new_T` for</div><div class="line"><a name="l04076"></a><span class="lineno"> 4076</span>&#160;class/struct/template type `T` that soapcpp2 auto-generates to create instances</div><div class="line"><a name="l04077"></a><span class="lineno"> 4077</span>&#160;on a context-managed heap:</div><div class="line"><a name="l04078"></a><span class="lineno"> 4078</span>&#160;</div><div class="line"><a name="l04079"></a><span class="lineno"> 4079</span>&#160;- `T * soap_new_T(struct soap*)` returns a new instance of `T` with default data</div><div class="line"><a name="l04080"></a><span class="lineno"> 4080</span>&#160;  member initializations that are set with the soapcpp2 auto-generated `void</div><div class="line"><a name="l04081"></a><span class="lineno"> 4081</span>&#160;  T::soap_default(struct soap*)` method), but ONLY IF the soapcpp2</div><div class="line"><a name="l04082"></a><span class="lineno"> 4082</span>&#160;  auto-generated default constructor is used that invokes `soap_default()` and</div><div class="line"><a name="l04083"></a><span class="lineno"> 4083</span>&#160;  was not replaced by a user-defined default constructor.</div><div class="line"><a name="l04084"></a><span class="lineno"> 4084</span>&#160;</div><div class="line"><a name="l04085"></a><span class="lineno"> 4085</span>&#160;- `T * soap_new_T(struct soap*, int n)` returns an array of `n` new instances of</div><div class="line"><a name="l04086"></a><span class="lineno"> 4086</span>&#160;  `T`.  Similar to the above, instances are initialized.</div><div class="line"><a name="l04087"></a><span class="lineno"> 4087</span>&#160;</div><div class="line"><a name="l04088"></a><span class="lineno"> 4088</span>&#160;- `T * soap_new_req_T(struct soap*, ...)` returns a new instance of `T` and sets</div><div class="line"><a name="l04089"></a><span class="lineno"> 4089</span>&#160;  the required data members to the values specified in `...`.  The required data</div><div class="line"><a name="l04090"></a><span class="lineno"> 4090</span>&#160;  members are those with nonzero minOccurs, see the subsections on</div><div class="line"><a name="l04091"></a><span class="lineno"> 4091</span>&#160;  [(smart) pointer members and their occurrence constraints](#toxsd9-8) and</div><div class="line"><a name="l04092"></a><span class="lineno"> 4092</span>&#160;  [container and array members and their occurrence constraints](#toxsd9-9).</div><div class="line"><a name="l04093"></a><span class="lineno"> 4093</span>&#160;</div><div class="line"><a name="l04094"></a><span class="lineno"> 4094</span>&#160;- `T * soap_new_set_T(struct soap*, ...)` returns a new instance of `T` and sets</div><div class="line"><a name="l04095"></a><span class="lineno"> 4095</span>&#160;  the public/serializable data members to the values specified in `...`.</div><div class="line"><a name="l04096"></a><span class="lineno"> 4096</span>&#160;</div><div class="line"><a name="l04097"></a><span class="lineno"> 4097</span>&#160;The above functions can be invoked with a NULL `soap` context, but we will be</div><div class="line"><a name="l04098"></a><span class="lineno"> 4098</span>&#160;responsible to use `delete T` to remove this instance from the unmanaged heap.</div><div class="line"><a name="l04099"></a><span class="lineno"> 4099</span>&#160;</div><div class="line"><a name="l04100"></a><span class="lineno"> 4100</span>&#160;The allocation functions return NULL when memory allocation failed.</div><div class="line"><a name="l04101"></a><span class="lineno"> 4101</span>&#160;</div><div class="line"><a name="l04102"></a><span class="lineno"> 4102</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l04103"></a><span class="lineno"> 4103</span>&#160;</div><div class="line"><a name="l04104"></a><span class="lineno"> 4104</span>&#160;Special classes and structs                                           {#toxsd10}</div><div class="line"><a name="l04105"></a><span class="lineno"> 4105</span>&#160;---------------------------</div><div class="line"><a name="l04106"></a><span class="lineno"> 4106</span>&#160;</div><div class="line"><a name="l04107"></a><span class="lineno"> 4107</span>&#160;The following applies to both structs and classes.  The examples show classes</div><div class="line"><a name="l04108"></a><span class="lineno"> 4108</span>&#160;in C++.  For C, use structs and omit the C++ features.  Structs also require</div><div class="line"><a name="l04109"></a><span class="lineno"> 4109</span>&#160;the use of the `struct` keyword, otherwise soapcpp2 will throw a syntax error.</div><div class="line"><a name="l04110"></a><span class="lineno"> 4110</span>&#160;</div><div class="line"><a name="l04111"></a><span class="lineno"> 4111</span>&#160;### SOAP-encoded arrays                                             {#toxsd10-1}</div><div class="line"><a name="l04112"></a><span class="lineno"> 4112</span>&#160;</div><div class="line"><a name="l04113"></a><span class="lineno"> 4113</span>&#160;A class or struct with the following layout is a one-dimensional SOAP-encoded</div><div class="line"><a name="l04114"></a><span class="lineno"> 4114</span>&#160;array type:</div><div class="line"><a name="l04115"></a><span class="lineno"> 4115</span>&#160;</div><div class="line"><a name="l04116"></a><span class="lineno"> 4116</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04117"></a><span class="lineno"> 4117</span>&#160;    class ArrayOfT</div><div class="line"><a name="l04118"></a><span class="lineno"> 4118</span>&#160;    {</div><div class="line"><a name="l04119"></a><span class="lineno"> 4119</span>&#160;     public:</div><div class="line"><a name="l04120"></a><span class="lineno"> 4120</span>&#160;        T   *__ptr;  // array pointer</div><div class="line"><a name="l04121"></a><span class="lineno"> 4121</span>&#160;        int  __size; // array size</div><div class="line"><a name="l04122"></a><span class="lineno"> 4122</span>&#160;    };</div><div class="line"><a name="l04123"></a><span class="lineno"> 4123</span>&#160;~~~</div><div class="line"><a name="l04124"></a><span class="lineno"> 4124</span>&#160;</div><div class="line"><a name="l04125"></a><span class="lineno"> 4125</span>&#160;where `T` is the array element type.  A multidimensional SOAP Array is:</div><div class="line"><a name="l04126"></a><span class="lineno"> 4126</span>&#160;</div><div class="line"><a name="l04127"></a><span class="lineno"> 4127</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04128"></a><span class="lineno"> 4128</span>&#160;    class ArrayOfT</div><div class="line"><a name="l04129"></a><span class="lineno"> 4129</span>&#160;    {</div><div class="line"><a name="l04130"></a><span class="lineno"> 4130</span>&#160;     public:</div><div class="line"><a name="l04131"></a><span class="lineno"> 4131</span>&#160;        T   *__ptr;     // array pointer</div><div class="line"><a name="l04132"></a><span class="lineno"> 4132</span>&#160;        int  __size[N]; // array size of each dimension</div><div class="line"><a name="l04133"></a><span class="lineno"> 4133</span>&#160;    };</div><div class="line"><a name="l04134"></a><span class="lineno"> 4134</span>&#160;~~~</div><div class="line"><a name="l04135"></a><span class="lineno"> 4135</span>&#160;</div><div class="line"><a name="l04136"></a><span class="lineno"> 4136</span>&#160;where `N` is the constant number of dimensions.  The pointer points to an array</div><div class="line"><a name="l04137"></a><span class="lineno"> 4137</span>&#160;of `__size[0]*__size[1]* ... * __size[N-1]` elements.</div><div class="line"><a name="l04138"></a><span class="lineno"> 4138</span>&#160;</div><div class="line"><a name="l04139"></a><span class="lineno"> 4139</span>&#160;This maps to a complexType restriction of SOAP-ENC:Array in the</div><div class="line"><a name="l04140"></a><span class="lineno"> 4140</span>&#160;soapcpp2-generated XML schema:</div><div class="line"><a name="l04141"></a><span class="lineno"> 4141</span>&#160;</div><div class="line"><a name="l04142"></a><span class="lineno"> 4142</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l04143"></a><span class="lineno"> 4143</span>&#160;~~~{.xml}</div><div class="line"><a name="l04144"></a><span class="lineno"> 4144</span>&#160;    &lt;complexType name=&quot;ArrayOfT&quot;&gt;</div><div class="line"><a name="l04145"></a><span class="lineno"> 4145</span>&#160;      &lt;complexContent&gt;</div><div class="line"><a name="l04146"></a><span class="lineno"> 4146</span>&#160;        &lt;restriction base=&quot;SOAP-ENC:Array&quot;&gt;</div><div class="line"><a name="l04147"></a><span class="lineno"> 4147</span>&#160;          &lt;sequence&gt;</div><div class="line"><a name="l04148"></a><span class="lineno"> 4148</span>&#160;            &lt;element name=&quot;item&quot; type=&quot;T&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;unbounded&quot; nillable=&quot;true&quot;/&gt;</div><div class="line"><a name="l04149"></a><span class="lineno"> 4149</span>&#160;          &lt;/sequence&gt;</div><div class="line"><a name="l04150"></a><span class="lineno"> 4150</span>&#160;          &lt;attribute ref=&quot;SOAP-ENC:arrayType&quot; WSDL:arrayType=&quot;ArrayOfT[]&quot;/&gt;</div><div class="line"><a name="l04151"></a><span class="lineno"> 4151</span>&#160;        &lt;/restriction&gt;</div><div class="line"><a name="l04152"></a><span class="lineno"> 4152</span>&#160;      &lt;/complexContent&gt;</div><div class="line"><a name="l04153"></a><span class="lineno"> 4153</span>&#160;    &lt;/complexType&gt;</div><div class="line"><a name="l04154"></a><span class="lineno"> 4154</span>&#160;~~~</div><div class="line"><a name="l04155"></a><span class="lineno"> 4155</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l04156"></a><span class="lineno"> 4156</span>&#160;</div><div class="line"><a name="l04157"></a><span class="lineno"> 4157</span>&#160;The name of the class can be arbitrary.  We often use `ArrayOfT` without a</div><div class="line"><a name="l04158"></a><span class="lineno"> 4158</span>&#160;prefix to distinguish arrays from other classes and structs.</div><div class="line"><a name="l04159"></a><span class="lineno"> 4159</span>&#160;</div><div class="line"><a name="l04160"></a><span class="lineno"> 4160</span>&#160;With SOAP 1.1 encoding, an optional offset member can be added that controls</div><div class="line"><a name="l04161"></a><span class="lineno"> 4161</span>&#160;the start of the index range for each dimension:</div><div class="line"><a name="l04162"></a><span class="lineno"> 4162</span>&#160;</div><div class="line"><a name="l04163"></a><span class="lineno"> 4163</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04164"></a><span class="lineno"> 4164</span>&#160;    class ArrayOfT</div><div class="line"><a name="l04165"></a><span class="lineno"> 4165</span>&#160;    {</div><div class="line"><a name="l04166"></a><span class="lineno"> 4166</span>&#160;     public:</div><div class="line"><a name="l04167"></a><span class="lineno"> 4167</span>&#160;        T   *__ptr;       // array pointer</div><div class="line"><a name="l04168"></a><span class="lineno"> 4168</span>&#160;        int  __size[N];   // array size of each dimension</div><div class="line"><a name="l04169"></a><span class="lineno"> 4169</span>&#160;        int  __offset[N]; // array offsets to start each dimension</div><div class="line"><a name="l04170"></a><span class="lineno"> 4170</span>&#160;    };</div><div class="line"><a name="l04171"></a><span class="lineno"> 4171</span>&#160;~~~</div><div class="line"><a name="l04172"></a><span class="lineno"> 4172</span>&#160;</div><div class="line"><a name="l04173"></a><span class="lineno"> 4173</span>&#160;For example, we can define a matrix of floats as follows:</div><div class="line"><a name="l04174"></a><span class="lineno"> 4174</span>&#160;</div><div class="line"><a name="l04175"></a><span class="lineno"> 4175</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04176"></a><span class="lineno"> 4176</span>&#160;    class Matrix</div><div class="line"><a name="l04177"></a><span class="lineno"> 4177</span>&#160;    {</div><div class="line"><a name="l04178"></a><span class="lineno"> 4178</span>&#160;     public:</div><div class="line"><a name="l04179"></a><span class="lineno"> 4179</span>&#160;        double *__ptr;</div><div class="line"><a name="l04180"></a><span class="lineno"> 4180</span>&#160;        int     __size[2];</div><div class="line"><a name="l04181"></a><span class="lineno"> 4181</span>&#160;    };</div><div class="line"><a name="l04182"></a><span class="lineno"> 4182</span>&#160;~~~</div><div class="line"><a name="l04183"></a><span class="lineno"> 4183</span>&#160;</div><div class="line"><a name="l04184"></a><span class="lineno"> 4184</span>&#160;The following code populates the matrix and serializes it in XML:</div><div class="line"><a name="l04185"></a><span class="lineno"> 4185</span>&#160;</div><div class="line"><a name="l04186"></a><span class="lineno"> 4186</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04187"></a><span class="lineno"> 4187</span>&#160;    soap *soap = soap_new1(SOAP_XML_INDENT);</div><div class="line"><a name="l04188"></a><span class="lineno"> 4188</span>&#160;    Matrix A;</div><div class="line"><a name="l04189"></a><span class="lineno"> 4189</span>&#160;    double a[6] = { 1, 2, 3, 4, 5, 6 };</div><div class="line"><a name="l04190"></a><span class="lineno"> 4190</span>&#160;    A.__ptr = a;</div><div class="line"><a name="l04191"></a><span class="lineno"> 4191</span>&#160;    A.__size[0] = 2;</div><div class="line"><a name="l04192"></a><span class="lineno"> 4192</span>&#160;    A.__size[1] = 3;</div><div class="line"><a name="l04193"></a><span class="lineno"> 4193</span>&#160;    soap_write_Matrix(soap, &amp;A);</div><div class="line"><a name="l04194"></a><span class="lineno"> 4194</span>&#160;~~~</div><div class="line"><a name="l04195"></a><span class="lineno"> 4195</span>&#160;</div><div class="line"><a name="l04196"></a><span class="lineno"> 4196</span>&#160;Matrix A is serialized as an array with 2x3 values:</div><div class="line"><a name="l04197"></a><span class="lineno"> 4197</span>&#160;</div><div class="line"><a name="l04198"></a><span class="lineno"> 4198</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l04199"></a><span class="lineno"> 4199</span>&#160;~~~{.xml}</div><div class="line"><a name="l04200"></a><span class="lineno"> 4200</span>&#160;    &lt;SOAP-ENC:Array SOAP-ENC:arrayType=&quot;xsd:double[2,3]&quot; ...&gt;</div><div class="line"><a name="l04201"></a><span class="lineno"> 4201</span>&#160;      &lt;item&gt;1&lt;/item&gt;</div><div class="line"><a name="l04202"></a><span class="lineno"> 4202</span>&#160;      &lt;item&gt;2&lt;/item&gt;</div><div class="line"><a name="l04203"></a><span class="lineno"> 4203</span>&#160;      &lt;item&gt;3&lt;/item&gt;</div><div class="line"><a name="l04204"></a><span class="lineno"> 4204</span>&#160;      &lt;item&gt;4&lt;/item&gt;</div><div class="line"><a name="l04205"></a><span class="lineno"> 4205</span>&#160;      &lt;item&gt;5&lt;/item&gt;</div><div class="line"><a name="l04206"></a><span class="lineno"> 4206</span>&#160;      &lt;item&gt;6&lt;/item&gt;</div><div class="line"><a name="l04207"></a><span class="lineno"> 4207</span>&#160;    &lt;/SOAP-ENC:Array&gt;</div><div class="line"><a name="l04208"></a><span class="lineno"> 4208</span>&#160;~~~</div><div class="line"><a name="l04209"></a><span class="lineno"> 4209</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l04210"></a><span class="lineno"> 4210</span>&#160;</div><div class="line"><a name="l04211"></a><span class="lineno"> 4211</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l04212"></a><span class="lineno"> 4212</span>&#160;</div><div class="line"><a name="l04213"></a><span class="lineno"> 4213</span>&#160;### XSD hexBinary and base64Binary types                            {#toxsd10-2}</div><div class="line"><a name="l04214"></a><span class="lineno"> 4214</span>&#160;</div><div class="line"><a name="l04215"></a><span class="lineno"> 4215</span>&#160;A special case of a one-dimensional array is used to define &lt;i&gt;`xsd:hexBinary`&lt;/i&gt; and</div><div class="line"><a name="l04216"></a><span class="lineno"> 4216</span>&#160;&lt;i&gt;`xsd:base64Binary`&lt;/i&gt; types when the pointer type is `unsigned char`:</div><div class="line"><a name="l04217"></a><span class="lineno"> 4217</span>&#160;</div><div class="line"><a name="l04218"></a><span class="lineno"> 4218</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04219"></a><span class="lineno"> 4219</span>&#160;    class xsd__hexBinary</div><div class="line"><a name="l04220"></a><span class="lineno"> 4220</span>&#160;    {</div><div class="line"><a name="l04221"></a><span class="lineno"> 4221</span>&#160;     public:</div><div class="line"><a name="l04222"></a><span class="lineno"> 4222</span>&#160;        unsigned char *__ptr;  // points to raw binary data</div><div class="line"><a name="l04223"></a><span class="lineno"> 4223</span>&#160;        int            __size; // size of data</div><div class="line"><a name="l04224"></a><span class="lineno"> 4224</span>&#160;    };</div><div class="line"><a name="l04225"></a><span class="lineno"> 4225</span>&#160;~~~</div><div class="line"><a name="l04226"></a><span class="lineno"> 4226</span>&#160;</div><div class="line"><a name="l04227"></a><span class="lineno"> 4227</span>&#160;and</div><div class="line"><a name="l04228"></a><span class="lineno"> 4228</span>&#160;</div><div class="line"><a name="l04229"></a><span class="lineno"> 4229</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04230"></a><span class="lineno"> 4230</span>&#160;    class xsd__base64Binary</div><div class="line"><a name="l04231"></a><span class="lineno"> 4231</span>&#160;    {</div><div class="line"><a name="l04232"></a><span class="lineno"> 4232</span>&#160;     public:</div><div class="line"><a name="l04233"></a><span class="lineno"> 4233</span>&#160;        unsigned char *__ptr;  // points to raw binary data</div><div class="line"><a name="l04234"></a><span class="lineno"> 4234</span>&#160;        int            __size; // size of data</div><div class="line"><a name="l04235"></a><span class="lineno"> 4235</span>&#160;    };</div><div class="line"><a name="l04236"></a><span class="lineno"> 4236</span>&#160;~~~</div><div class="line"><a name="l04237"></a><span class="lineno"> 4237</span>&#160;</div><div class="line"><a name="l04238"></a><span class="lineno"> 4238</span>&#160;To create a new binary type, use either one of the following three forms that</div><div class="line"><a name="l04239"></a><span class="lineno"> 4239</span>&#160;declare a new `ns__binary` type that is a &lt;i&gt;`simpleType`&lt;/i&gt; restriction of</div><div class="line"><a name="l04240"></a><span class="lineno"> 4240</span>&#160;&lt;i&gt;`xsd:base64Binary`&lt;/i&gt;:</div><div class="line"><a name="l04241"></a><span class="lineno"> 4241</span>&#160;</div><div class="line"><a name="l04242"></a><span class="lineno"> 4242</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04243"></a><span class="lineno"> 4243</span>&#160;    typedef xsd__base64Binary ns__binary;</div><div class="line"><a name="l04244"></a><span class="lineno"> 4244</span>&#160;~~~</div><div class="line"><a name="l04245"></a><span class="lineno"> 4245</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04246"></a><span class="lineno"> 4246</span>&#160;    class ns__binary : public xsd__base64Binary</div><div class="line"><a name="l04247"></a><span class="lineno"> 4247</span>&#160;    {</div><div class="line"><a name="l04248"></a><span class="lineno"> 4248</span>&#160;        ... // attribute members (@) and class methods</div><div class="line"><a name="l04249"></a><span class="lineno"> 4249</span>&#160;    };</div><div class="line"><a name="l04250"></a><span class="lineno"> 4250</span>&#160;~~~</div><div class="line"><a name="l04251"></a><span class="lineno"> 4251</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04252"></a><span class="lineno"> 4252</span>&#160;    class ns__binary</div><div class="line"><a name="l04253"></a><span class="lineno"> 4253</span>&#160;    {</div><div class="line"><a name="l04254"></a><span class="lineno"> 4254</span>&#160;     public:</div><div class="line"><a name="l04255"></a><span class="lineno"> 4255</span>&#160;        unsigned char *__ptr;  // points to raw binary data</div><div class="line"><a name="l04256"></a><span class="lineno"> 4256</span>&#160;        int            __size; // size of data</div><div class="line"><a name="l04257"></a><span class="lineno"> 4257</span>&#160;        ...                    // attribute members (@) and class methods (optional)</div><div class="line"><a name="l04258"></a><span class="lineno"> 4258</span>&#160;    };</div><div class="line"><a name="l04259"></a><span class="lineno"> 4259</span>&#160;~~~</div><div class="line"><a name="l04260"></a><span class="lineno"> 4260</span>&#160;</div><div class="line"><a name="l04261"></a><span class="lineno"> 4261</span>&#160;Here, `xsd__base64Binary` is reused in the first two cases, where</div><div class="line"><a name="l04262"></a><span class="lineno"> 4262</span>&#160;`xsd__base64Binary` is declared as shown above.</div><div class="line"><a name="l04263"></a><span class="lineno"> 4263</span>&#160;</div><div class="line"><a name="l04264"></a><span class="lineno"> 4264</span>&#160;@see [DIME/MIME/MTOM attachment binary types](#toxsd10-3)</div><div class="line"><a name="l04265"></a><span class="lineno"> 4265</span>&#160;</div><div class="line"><a name="l04266"></a><span class="lineno"> 4266</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l04267"></a><span class="lineno"> 4267</span>&#160;</div><div class="line"><a name="l04268"></a><span class="lineno"> 4268</span>&#160;### DIME/MIME/MTOM attachment binary types                          {#toxsd10-3}</div><div class="line"><a name="l04269"></a><span class="lineno"> 4269</span>&#160;</div><div class="line"><a name="l04270"></a><span class="lineno"> 4270</span>&#160;A class or struct with a binary content layout can be extended to support</div><div class="line"><a name="l04271"></a><span class="lineno"> 4271</span>&#160;attachments.  The following struct or class type can be used as DIME, MIME, and</div><div class="line"><a name="l04272"></a><span class="lineno"> 4272</span>&#160;MTOM attachment and also be used for &lt;i&gt;`xsd:base64Binary`&lt;/i&gt; type values:</div><div class="line"><a name="l04273"></a><span class="lineno"> 4273</span>&#160;</div><div class="line"><a name="l04274"></a><span class="lineno"> 4274</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04275"></a><span class="lineno"> 4275</span>&#160;    class xsd__base64Binary</div><div class="line"><a name="l04276"></a><span class="lineno"> 4276</span>&#160;    {</div><div class="line"><a name="l04277"></a><span class="lineno"> 4277</span>&#160;     public:</div><div class="line"><a name="l04278"></a><span class="lineno"> 4278</span>&#160;        unsigned char *__ptr;   // points to raw binary data</div><div class="line"><a name="l04279"></a><span class="lineno"> 4279</span>&#160;        int            __size;  // size of data</div><div class="line"><a name="l04280"></a><span class="lineno"> 4280</span>&#160;        char          *id;      // NULL to generate an id, or set to a unique UUID</div><div class="line"><a name="l04281"></a><span class="lineno"> 4281</span>&#160;        char          *type;    // MIME type of the data</div><div class="line"><a name="l04282"></a><span class="lineno"> 4282</span>&#160;        char          *options; // optional description of MIME attachment</div><div class="line"><a name="l04283"></a><span class="lineno"> 4283</span>&#160;    };</div><div class="line"><a name="l04284"></a><span class="lineno"> 4284</span>&#160;~~~</div><div class="line"><a name="l04285"></a><span class="lineno"> 4285</span>&#160;</div><div class="line"><a name="l04286"></a><span class="lineno"> 4286</span>&#160;When the `id`, `type`, or `options` members are non-NULL, an attachment will be</div><div class="line"><a name="l04287"></a><span class="lineno"> 4287</span>&#160;used instead of base64 XML content.  DIME attachments are the default.  To</div><div class="line"><a name="l04288"></a><span class="lineno"> 4288</span>&#160;switch to MIME use the `SOAP_ENC_MIME` context flag.  To switch to MTOM use the</div><div class="line"><a name="l04289"></a><span class="lineno"> 4289</span>&#160;`SOAP_ENC_MTOM` context flag.</div><div class="line"><a name="l04290"></a><span class="lineno"> 4290</span>&#160;</div><div class="line"><a name="l04291"></a><span class="lineno"> 4291</span>&#160;MTOM is typically used with XOP &lt;i&gt;`&lt;xop:Include&gt;`&lt;/i&gt; elements, which is</div><div class="line"><a name="l04292"></a><span class="lineno"> 4292</span>&#160;preferred and declared as follows:</div><div class="line"><a name="l04293"></a><span class="lineno"> 4293</span>&#160;</div><div class="line"><a name="l04294"></a><span class="lineno"> 4294</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04295"></a><span class="lineno"> 4295</span>&#160;    //gsoap xop schema import: http://www.w3.org/2004/08/xop/include</div><div class="line"><a name="l04296"></a><span class="lineno"> 4296</span>&#160;    class _xop__Include</div><div class="line"><a name="l04297"></a><span class="lineno"> 4297</span>&#160;    {</div><div class="line"><a name="l04298"></a><span class="lineno"> 4298</span>&#160;     public:</div><div class="line"><a name="l04299"></a><span class="lineno"> 4299</span>&#160;        unsigned char *__ptr;   // points to raw binary data</div><div class="line"><a name="l04300"></a><span class="lineno"> 4300</span>&#160;        int            __size;  // size of data</div><div class="line"><a name="l04301"></a><span class="lineno"> 4301</span>&#160;        char          *id;      // NULL to generate an id, or set to a unique UUID</div><div class="line"><a name="l04302"></a><span class="lineno"> 4302</span>&#160;        char          *type;    // MIME type of the data</div><div class="line"><a name="l04303"></a><span class="lineno"> 4303</span>&#160;        char          *options; // optional description of MIME attachment</div><div class="line"><a name="l04304"></a><span class="lineno"> 4304</span>&#160;    };</div><div class="line"><a name="l04305"></a><span class="lineno"> 4305</span>&#160;~~~</div><div class="line"><a name="l04306"></a><span class="lineno"> 4306</span>&#160;</div><div class="line"><a name="l04307"></a><span class="lineno"> 4307</span>&#160;Attachments are beyond the scope of this article.  See the</div><div class="line"><a name="l04308"></a><span class="lineno"> 4308</span>&#160;[gSOAP user guide.](../../guide/html/index.html) for more details.</div><div class="line"><a name="l04309"></a><span class="lineno"> 4309</span>&#160;</div><div class="line"><a name="l04310"></a><span class="lineno"> 4310</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l04311"></a><span class="lineno"> 4311</span>&#160;</div><div class="line"><a name="l04312"></a><span class="lineno"> 4312</span>&#160;### Wrapper class/struct with simpleContent                         {#toxsd10-4}</div><div class="line"><a name="l04313"></a><span class="lineno"> 4313</span>&#160;</div><div class="line"><a name="l04314"></a><span class="lineno"> 4314</span>&#160;A class or struct with the following layout is a complexType that wraps</div><div class="line"><a name="l04315"></a><span class="lineno"> 4315</span>&#160;simpleContent:</div><div class="line"><a name="l04316"></a><span class="lineno"> 4316</span>&#160;</div><div class="line"><a name="l04317"></a><span class="lineno"> 4317</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04318"></a><span class="lineno"> 4318</span>&#160;    class ns__simple</div><div class="line"><a name="l04319"></a><span class="lineno"> 4319</span>&#160;    {</div><div class="line"><a name="l04320"></a><span class="lineno"> 4320</span>&#160;     public:</div><div class="line"><a name="l04321"></a><span class="lineno"> 4321</span>&#160;        T   __item; // primitive type for the simpleContent</div><div class="line"><a name="l04322"></a><span class="lineno"> 4322</span>&#160;        ...         // attribute members (@) and class methods (optional)</div><div class="line"><a name="l04323"></a><span class="lineno"> 4323</span>&#160;    };</div><div class="line"><a name="l04324"></a><span class="lineno"> 4324</span>&#160;~~~</div><div class="line"><a name="l04325"></a><span class="lineno"> 4325</span>&#160;</div><div class="line"><a name="l04326"></a><span class="lineno"> 4326</span>&#160;The type `T` is a primitive type (`bool`, `enum`, `time_t`, numeric and string</div><div class="line"><a name="l04327"></a><span class="lineno"> 4327</span>&#160;types), `xsd__hexBinary`, `xsd__base64Binary`, and custom serializers, such as</div><div class="line"><a name="l04328"></a><span class="lineno"> 4328</span>&#160;`xsd__dateTime`.</div><div class="line"><a name="l04329"></a><span class="lineno"> 4329</span>&#160;</div><div class="line"><a name="l04330"></a><span class="lineno"> 4330</span>&#160;This maps to a complexType with simpleContent in the soapcpp2-generated XML</div><div class="line"><a name="l04331"></a><span class="lineno"> 4331</span>&#160;schema:</div><div class="line"><a name="l04332"></a><span class="lineno"> 4332</span>&#160;</div><div class="line"><a name="l04333"></a><span class="lineno"> 4333</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l04334"></a><span class="lineno"> 4334</span>&#160;~~~{.xml}</div><div class="line"><a name="l04335"></a><span class="lineno"> 4335</span>&#160;    &lt;complexType name=&quot;simple&quot;&gt;</div><div class="line"><a name="l04336"></a><span class="lineno"> 4336</span>&#160;      &lt;simpleContent&gt;</div><div class="line"><a name="l04337"></a><span class="lineno"> 4337</span>&#160;        &lt;extension base=&quot;T&quot;/&gt;</div><div class="line"><a name="l04338"></a><span class="lineno"> 4338</span>&#160;      &lt;/simpleContent&gt;</div><div class="line"><a name="l04339"></a><span class="lineno"> 4339</span>&#160;    &lt;/complexType&gt; </div><div class="line"><a name="l04340"></a><span class="lineno"> 4340</span>&#160;~~~</div><div class="line"><a name="l04341"></a><span class="lineno"> 4341</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l04342"></a><span class="lineno"> 4342</span>&#160;</div><div class="line"><a name="l04343"></a><span class="lineno"> 4343</span>&#160;A wrapper class/struct may include any number of members that are declared as</div><div class="line"><a name="l04344"></a><span class="lineno"> 4344</span>&#160;attributes with `@`, which should be placed after the `__item` member.</div><div class="line"><a name="l04345"></a><span class="lineno"> 4345</span>&#160;</div><div class="line"><a name="l04346"></a><span class="lineno"> 4346</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l04347"></a><span class="lineno"> 4347</span>&#160;</div><div class="line"><a name="l04348"></a><span class="lineno"> 4348</span>&#160;### DOM anyType and anyAttribute                                    {#toxsd10-5}</div><div class="line"><a name="l04349"></a><span class="lineno"> 4349</span>&#160;</div><div class="line"><a name="l04350"></a><span class="lineno"> 4350</span>&#160;Use of a DOM is optional and enabled by `#import &quot;dom.h&quot;` to use the DOM</div><div class="line"><a name="l04351"></a><span class="lineno"> 4351</span>&#160;`xsd__anyType` element node and `xsd__anyAttribute` attribute node:</div><div class="line"><a name="l04352"></a><span class="lineno"> 4352</span>&#160;</div><div class="line"><a name="l04353"></a><span class="lineno"> 4353</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04354"></a><span class="lineno"> 4354</span>&#160;    #import &quot;dom.h&quot;</div><div class="line"><a name="l04355"></a><span class="lineno"> 4355</span>&#160;</div><div class="line"><a name="l04356"></a><span class="lineno"> 4356</span>&#160;    class ns__record</div><div class="line"><a name="l04357"></a><span class="lineno"> 4357</span>&#160;    {</div><div class="line"><a name="l04358"></a><span class="lineno"> 4358</span>&#160;     public:</div><div class="line"><a name="l04359"></a><span class="lineno"> 4359</span>&#160;      @ xsd__anyAttribute attributes;  // optional DOM attributes</div><div class="line"><a name="l04360"></a><span class="lineno"> 4360</span>&#160;        xsd__anyType      *name;       // optional DOM element (pointer means minOccurs=0)</div><div class="line"><a name="l04361"></a><span class="lineno"> 4361</span>&#160;        xsd__anyType       address;    // required DOM element (minOccurs=1)</div><div class="line"><a name="l04362"></a><span class="lineno"> 4362</span>&#160;        xsd__anyType       email   0;  // optional DOM element (minOccurs=0)</div><div class="line"><a name="l04363"></a><span class="lineno"> 4363</span>&#160;        ...                            // other members</div><div class="line"><a name="l04364"></a><span class="lineno"> 4364</span>&#160;    };</div><div class="line"><a name="l04365"></a><span class="lineno"> 4365</span>&#160;~~~</div><div class="line"><a name="l04366"></a><span class="lineno"> 4366</span>&#160;</div><div class="line"><a name="l04367"></a><span class="lineno"> 4367</span>&#160;where `name` contains XML stored in a DOM node set and `attributes` is a list</div><div class="line"><a name="l04368"></a><span class="lineno"> 4368</span>&#160;of all visibly rendered attributes.  The name `attributes` is arbitrary and any</div><div class="line"><a name="l04369"></a><span class="lineno"> 4369</span>&#160;name will suffice.</div><div class="line"><a name="l04370"></a><span class="lineno"> 4370</span>&#160;</div><div class="line"><a name="l04371"></a><span class="lineno"> 4371</span>&#160;You should place the `xsd__anyType` members at the end of the struct or class.</div><div class="line"><a name="l04372"></a><span class="lineno"> 4372</span>&#160;This ensures that the DOM members are populated last as a &quot;catch all&quot;.  A</div><div class="line"><a name="l04373"></a><span class="lineno"> 4373</span>&#160;member name starting with double underscore is a wildcard member.  These</div><div class="line"><a name="l04374"></a><span class="lineno"> 4374</span>&#160;members are placed at the end of a struct or class automatically by soapcpp2.</div><div class="line"><a name="l04375"></a><span class="lineno"> 4375</span>&#160;</div><div class="line"><a name="l04376"></a><span class="lineno"> 4376</span>&#160;An `#import &quot;dom.h&quot;` import is automatically added by &lt;b&gt;`wsdl2h -d`&lt;/b&gt; with</div><div class="line"><a name="l04377"></a><span class="lineno"> 4377</span>&#160;option &lt;b&gt;`-d`&lt;/b&gt; to bind &lt;i&gt;`xsd:anyType`&lt;/i&gt; to DOM nodes, and also to</div><div class="line"><a name="l04378"></a><span class="lineno"> 4378</span>&#160;populate &lt;i&gt;`xsd:any`&lt;/i&gt;, &lt;i&gt;`xsd:anyAttribute`&lt;/i&gt; and &lt;i&gt;`xsd:mixed`&lt;/i&gt; XML</div><div class="line"><a name="l04379"></a><span class="lineno"> 4379</span>&#160;content:</div><div class="line"><a name="l04380"></a><span class="lineno"> 4380</span>&#160;</div><div class="line"><a name="l04381"></a><span class="lineno"> 4381</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04382"></a><span class="lineno"> 4382</span>&#160;    #import &quot;dom.h&quot;</div><div class="line"><a name="l04383"></a><span class="lineno"> 4383</span>&#160;</div><div class="line"><a name="l04384"></a><span class="lineno"> 4384</span>&#160;    class ns__record</div><div class="line"><a name="l04385"></a><span class="lineno"> 4385</span>&#160;    {</div><div class="line"><a name="l04386"></a><span class="lineno"> 4386</span>&#160;     public:</div><div class="line"><a name="l04387"></a><span class="lineno"> 4387</span>&#160;      @ xsd__anyAttribute        __anyAttribute;  // optional DOM attributes</div><div class="line"><a name="l04388"></a><span class="lineno"> 4388</span>&#160;        std::vector&lt;xsd__anyType&gt; __any   0;      // optional DOM elements (minOccurs=0)</div><div class="line"><a name="l04389"></a><span class="lineno"> 4389</span>&#160;        xsd__anyType              __mixed 0;      // optional mixed content (minOccurs=0)</div><div class="line"><a name="l04390"></a><span class="lineno"> 4390</span>&#160;        ...                                       // other members</div><div class="line"><a name="l04391"></a><span class="lineno"> 4391</span>&#160;    };</div><div class="line"><a name="l04392"></a><span class="lineno"> 4392</span>&#160;~~~</div><div class="line"><a name="l04393"></a><span class="lineno"> 4393</span>&#160;</div><div class="line"><a name="l04394"></a><span class="lineno"> 4394</span>&#160;where the members prefixed with `__` are &quot;invisible&quot; to the XML parser, meaning</div><div class="line"><a name="l04395"></a><span class="lineno"> 4395</span>&#160;that these members are not bound to XML tag names.</div><div class="line"><a name="l04396"></a><span class="lineno"> 4396</span>&#160;</div><div class="line"><a name="l04397"></a><span class="lineno"> 4397</span>&#160;In C you can use a dynamic arrary instead of `std::vector`:</div><div class="line"><a name="l04398"></a><span class="lineno"> 4398</span>&#160;</div><div class="line"><a name="l04399"></a><span class="lineno"> 4399</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04400"></a><span class="lineno"> 4400</span>&#160;    #import &quot;dom.h&quot;</div><div class="line"><a name="l04401"></a><span class="lineno"> 4401</span>&#160;</div><div class="line"><a name="l04402"></a><span class="lineno"> 4402</span>&#160;    struct ns__record</div><div class="line"><a name="l04403"></a><span class="lineno"> 4403</span>&#160;    {</div><div class="line"><a name="l04404"></a><span class="lineno"> 4404</span>&#160;      @ xsd__anyAttribute        __anyAttribute; // optional DOM attributes</div><div class="line"><a name="l04405"></a><span class="lineno"> 4405</span>&#160;      $ int                      __sizeOfany;    // size of the array</div><div class="line"><a name="l04406"></a><span class="lineno"> 4406</span>&#160;        xsd__anyType             *__any;         // optional DOM elements (pointer means minOccurs=0)</div><div class="line"><a name="l04407"></a><span class="lineno"> 4407</span>&#160;        xsd__anyType              __mixed 0;     // optional mixed content (minOccurs=0)</div><div class="line"><a name="l04408"></a><span class="lineno"> 4408</span>&#160;        ...                                      // other members</div><div class="line"><a name="l04409"></a><span class="lineno"> 4409</span>&#160;    };</div><div class="line"><a name="l04410"></a><span class="lineno"> 4410</span>&#160;~~~</div><div class="line"><a name="l04411"></a><span class="lineno"> 4411</span>&#160;</div><div class="line"><a name="l04412"></a><span class="lineno"> 4412</span>&#160;Classes can inherit DOM, which enables full use of polymorphism with one base</div><div class="line"><a name="l04413"></a><span class="lineno"> 4413</span>&#160;DOM class:</div><div class="line"><a name="l04414"></a><span class="lineno"> 4414</span>&#160;</div><div class="line"><a name="l04415"></a><span class="lineno"> 4415</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04416"></a><span class="lineno"> 4416</span>&#160;    #import &quot;dom.h&quot;</div><div class="line"><a name="l04417"></a><span class="lineno"> 4417</span>&#160;</div><div class="line"><a name="l04418"></a><span class="lineno"> 4418</span>&#160;    class ns__record : public xsd__anyType</div><div class="line"><a name="l04419"></a><span class="lineno"> 4419</span>&#160;    {</div><div class="line"><a name="l04420"></a><span class="lineno"> 4420</span>&#160;     public:</div><div class="line"><a name="l04421"></a><span class="lineno"> 4421</span>&#160;        std::vector&lt;xsd__anyType*&gt; array; // array of objects of any class</div><div class="line"><a name="l04422"></a><span class="lineno"> 4422</span>&#160;        ...                               // other members</div><div class="line"><a name="l04423"></a><span class="lineno"> 4423</span>&#160;    };</div><div class="line"><a name="l04424"></a><span class="lineno"> 4424</span>&#160;~~~</div><div class="line"><a name="l04425"></a><span class="lineno"> 4425</span>&#160;</div><div class="line"><a name="l04426"></a><span class="lineno"> 4426</span>&#160;This permits an `xsd__anyType` pointer to refer to a derived class such as</div><div class="line"><a name="l04427"></a><span class="lineno"> 4427</span>&#160;`ns__record`, which will be serialized with an &lt;i&gt;`xsi:type`&lt;/i&gt; attribute that is</div><div class="line"><a name="l04428"></a><span class="lineno"> 4428</span>&#160;set to &quot;ns:record&quot;.  The &lt;i&gt;`xsi:type`&lt;/i&gt; attributes add the necessary type information</div><div class="line"><a name="l04429"></a><span class="lineno"> 4429</span>&#160;to distinguish the XML content from the DOM base type.  This is important for</div><div class="line"><a name="l04430"></a><span class="lineno"> 4430</span>&#160;the receiving end: without &lt;i&gt;`xsd:type`&lt;/i&gt; attributes with type names, only base DOM</div><div class="line"><a name="l04431"></a><span class="lineno"> 4431</span>&#160;objects are recognized and instantiated.</div><div class="line"><a name="l04432"></a><span class="lineno"> 4432</span>&#160;</div><div class="line"><a name="l04433"></a><span class="lineno"> 4433</span>&#160;Because C lacks object-oriented programming concepts such as class inheritance</div><div class="line"><a name="l04434"></a><span class="lineno"> 4434</span>&#160;and polymorphism, you should consider using [derived types in C and C++](#toxsd9-1-1).</div><div class="line"><a name="l04435"></a><span class="lineno"> 4435</span>&#160;</div><div class="line"><a name="l04436"></a><span class="lineno"> 4436</span>&#160;An alternative is to use the special [tagged void pointer members](#toxsd9-12)</div><div class="line"><a name="l04437"></a><span class="lineno"> 4437</span>&#160;to serialize data pointed to by a `void*` member, which can be any serializable</div><div class="line"><a name="l04438"></a><span class="lineno"> 4438</span>&#160;type, such as derived types.  This approach uses &lt;i&gt;`xsi:type`&lt;/i&gt; attributes</div><div class="line"><a name="l04439"></a><span class="lineno"> 4439</span>&#160;to identify the type of value serialized.</div><div class="line"><a name="l04440"></a><span class="lineno"> 4440</span>&#160;</div><div class="line"><a name="l04441"></a><span class="lineno"> 4441</span>&#160;To ensure that wsdl2h generates pointer-based `xsd__anyType` DOM nodes with</div><div class="line"><a name="l04442"></a><span class="lineno"> 4442</span>&#160;&lt;b&gt;`wsdl2h -d`&lt;/b&gt; using option &lt;b&gt;`-d`&lt;/b&gt; for &lt;i&gt;`xsd:any`&lt;/i&gt;, add the</div><div class="line"><a name="l04443"></a><span class="lineno"> 4443</span>&#160;following line to &lt;i&gt;`typemap.dat`&lt;/i&gt;:</div><div class="line"><a name="l04444"></a><span class="lineno"> 4444</span>&#160;</div><div class="line"><a name="l04445"></a><span class="lineno"> 4445</span>&#160;    xsd__any = | xsd__anyType*</div><div class="line"><a name="l04446"></a><span class="lineno"> 4446</span>&#160;</div><div class="line"><a name="l04447"></a><span class="lineno"> 4447</span>&#160;This lets wsdl2h produce class/struct members and containers with</div><div class="line"><a name="l04448"></a><span class="lineno"> 4448</span>&#160;`xsd__anyType*` for &lt;i&gt;`xsd:any`&lt;/i&gt; instead of `xsd__anyType`.  To just force all</div><div class="line"><a name="l04449"></a><span class="lineno"> 4449</span>&#160;&lt;i&gt;`xsd:anyType`&lt;/i&gt; uses to be pointer-based, declare in &lt;i&gt;`typemap.dat`&lt;/i&gt;:</div><div class="line"><a name="l04450"></a><span class="lineno"> 4450</span>&#160;</div><div class="line"><a name="l04451"></a><span class="lineno"> 4451</span>&#160;    xsd__anyType = | xsd__anyType*</div><div class="line"><a name="l04452"></a><span class="lineno"> 4452</span>&#160;</div><div class="line"><a name="l04453"></a><span class="lineno"> 4453</span>&#160;If you use &lt;b&gt;`wsdl2h -d -p`&lt;/b&gt; using options &lt;b&gt;`-d`&lt;/b&gt; and &lt;b&gt;`-p`&lt;/b&gt; then</div><div class="line"><a name="l04454"></a><span class="lineno"> 4454</span>&#160;every class will inherit DOM as shown above.  Without option `-d`, an</div><div class="line"><a name="l04455"></a><span class="lineno"> 4455</span>&#160;`xsd__anyType` type is generated to serve as the root type in the type</div><div class="line"><a name="l04456"></a><span class="lineno"> 4456</span>&#160;hierarchy:</div><div class="line"><a name="l04457"></a><span class="lineno"> 4457</span>&#160;</div><div class="line"><a name="l04458"></a><span class="lineno"> 4458</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04459"></a><span class="lineno"> 4459</span>&#160;    class xsd__anyType { _XML __item; struct soap *soap; };</div><div class="line"><a name="l04460"></a><span class="lineno"> 4460</span>&#160;</div><div class="line"><a name="l04461"></a><span class="lineno"> 4461</span>&#160;    class ns__record : public xsd__anyType</div><div class="line"><a name="l04462"></a><span class="lineno"> 4462</span>&#160;    {</div><div class="line"><a name="l04463"></a><span class="lineno"> 4463</span>&#160;        ...</div><div class="line"><a name="l04464"></a><span class="lineno"> 4464</span>&#160;    };</div><div class="line"><a name="l04465"></a><span class="lineno"> 4465</span>&#160;~~~</div><div class="line"><a name="l04466"></a><span class="lineno"> 4466</span>&#160;</div><div class="line"><a name="l04467"></a><span class="lineno"> 4467</span>&#160;where the `_XML __item` member holds any XML content as a literal XML string.</div><div class="line"><a name="l04468"></a><span class="lineno"> 4468</span>&#160;</div><div class="line"><a name="l04469"></a><span class="lineno"> 4469</span>&#160;To use the DOM API, compile &lt;i&gt;`dom.c`&lt;/i&gt; (or &lt;i&gt;`dom.cpp`&lt;/i&gt; for C++), or</div><div class="line"><a name="l04470"></a><span class="lineno"> 4470</span>&#160;link the gSOAP library with &lt;b&gt;`-lgsoapssl`&lt;/b&gt; (or &lt;b&gt;`-lgsoapssl++`&lt;/b&gt; for C++).</div><div class="line"><a name="l04471"></a><span class="lineno"> 4471</span>&#160;</div><div class="line"><a name="l04472"></a><span class="lineno"> 4472</span>&#160;@see Documentation of [XML DOM and XPath](http://www.genivia.com/doc/dom/html)</div><div class="line"><a name="l04473"></a><span class="lineno"> 4473</span>&#160;for more details.</div><div class="line"><a name="l04474"></a><span class="lineno"> 4474</span>&#160;</div><div class="line"><a name="l04475"></a><span class="lineno"> 4475</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l04476"></a><span class="lineno"> 4476</span>&#160;</div><div class="line"><a name="l04477"></a><span class="lineno"> 4477</span>&#160;Directives                                                         {#directives}</div><div class="line"><a name="l04478"></a><span class="lineno"> 4478</span>&#160;==========</div><div class="line"><a name="l04479"></a><span class="lineno"> 4479</span>&#160;</div><div class="line"><a name="l04480"></a><span class="lineno"> 4480</span>&#160;You can use `//gsoap` directives in the interface header file with the data</div><div class="line"><a name="l04481"></a><span class="lineno"> 4481</span>&#160;binding interface for soapcpp2.  These directives are used to configure the</div><div class="line"><a name="l04482"></a><span class="lineno"> 4482</span>&#160;code generated by soapcpp2 by declaring various.  properties of Web services</div><div class="line"><a name="l04483"></a><span class="lineno"> 4483</span>&#160;and XML schemas.  When using the wsdl2h tool, you will notice that wsdl2h</div><div class="line"><a name="l04484"></a><span class="lineno"> 4484</span>&#160;generates directives automatically based on the WSDL and XSD input.</div><div class="line"><a name="l04485"></a><span class="lineno"> 4485</span>&#160;</div><div class="line"><a name="l04486"></a><span class="lineno"> 4486</span>&#160;Service directives are applicable to service and operations described by WSDL.</div><div class="line"><a name="l04487"></a><span class="lineno"> 4487</span>&#160;Schema directives are applicable to types, elements, and attributes defined by</div><div class="line"><a name="l04488"></a><span class="lineno"> 4488</span>&#160;XML schemas.</div><div class="line"><a name="l04489"></a><span class="lineno"> 4489</span>&#160;</div><div class="line"><a name="l04490"></a><span class="lineno"> 4490</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l04491"></a><span class="lineno"> 4491</span>&#160;</div><div class="line"><a name="l04492"></a><span class="lineno"> 4492</span>&#160;Service directives                                               {#directives-1}</div><div class="line"><a name="l04493"></a><span class="lineno"> 4493</span>&#160;------------------</div><div class="line"><a name="l04494"></a><span class="lineno"> 4494</span>&#160;</div><div class="line"><a name="l04495"></a><span class="lineno"> 4495</span>&#160;A service directive must start at a new line and is of the form:</div><div class="line"><a name="l04496"></a><span class="lineno"> 4496</span>&#160;</div><div class="line"><a name="l04497"></a><span class="lineno"> 4497</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04498"></a><span class="lineno"> 4498</span>&#160;    //gsoap &lt;prefix&gt; service &lt;property&gt;: &lt;value&gt;</div><div class="line"><a name="l04499"></a><span class="lineno"> 4499</span>&#160;~~~</div><div class="line"><a name="l04500"></a><span class="lineno"> 4500</span>&#160;</div><div class="line"><a name="l04501"></a><span class="lineno"> 4501</span>&#160;where `&lt;prefix&gt;` is the XML namespace prefix of a service binding.  The</div><div class="line"><a name="l04502"></a><span class="lineno"> 4502</span>&#160;`&lt;property&gt;` and `&lt;value&gt;` fields are one of the following:</div><div class="line"><a name="l04503"></a><span class="lineno"> 4503</span>&#160;</div><div class="line"><a name="l04504"></a><span class="lineno"> 4504</span>&#160;property        | value</div><div class="line"><a name="l04505"></a><span class="lineno"> 4505</span>&#160;--------------- | -----</div><div class="line"><a name="l04506"></a><span class="lineno"> 4506</span>&#160;`name`          | name of the service, optionally followed by text describing the service</div><div class="line"><a name="l04507"></a><span class="lineno"> 4507</span>&#160;`namespace`     | URI of the WSDL targetNamespace</div><div class="line"><a name="l04508"></a><span class="lineno"> 4508</span>&#160;`documentation` | text describing the service (see also the `name` property), multiple permitted</div><div class="line"><a name="l04509"></a><span class="lineno"> 4509</span>&#160;`doc`           | an alias for the `documentation` property</div><div class="line"><a name="l04510"></a><span class="lineno"> 4510</span>&#160;`style`         | `document` (default) SOAP messaging style or `rpc` for SOAP RPC</div><div class="line"><a name="l04511"></a><span class="lineno"> 4511</span>&#160;`encoding`      | `literal` (default), `encoded` for SOAP encoding, or a custom URI</div><div class="line"><a name="l04512"></a><span class="lineno"> 4512</span>&#160;`protocol`      | specifies SOAP or REST, see below</div><div class="line"><a name="l04513"></a><span class="lineno"> 4513</span>&#160;`port`          | URL of the service endpoint, usually an http or https address, to use in the WSDL definitions/service/port/address/\@location</div><div class="line"><a name="l04514"></a><span class="lineno"> 4514</span>&#160;`location`      | an alias for the `port` property</div><div class="line"><a name="l04515"></a><span class="lineno"> 4515</span>&#160;`endpoint`      | an alias for the `port` property</div><div class="line"><a name="l04516"></a><span class="lineno"> 4516</span>&#160;`transport`     | URI declaration of the transport, usually `http://schemas.xmlsoap.org/soap/http`</div><div class="line"><a name="l04517"></a><span class="lineno"> 4517</span>&#160;`definitions`   | name of the WSDL definitions/\@name</div><div class="line"><a name="l04518"></a><span class="lineno"> 4518</span>&#160;`type`          | name of the WSDL definitions/portType/\@name (WSDL2.0 interface/\@name)</div><div class="line"><a name="l04519"></a><span class="lineno"> 4519</span>&#160;`portType`      | an alias for the `type` property (`portType` follows SOAP 1.1 naming conventions)</div><div class="line"><a name="l04520"></a><span class="lineno"> 4520</span>&#160;`interface`     | an alias for the `type` property (`interface` follows SOAP 1.2 naming conventions)</div><div class="line"><a name="l04521"></a><span class="lineno"> 4521</span>&#160;`binding`       | name of the WSDL definitions/binding/\@name</div><div class="line"><a name="l04522"></a><span class="lineno"> 4522</span>&#160;`portName`      | name of the WSDL definitions/service/port/\@name</div><div class="line"><a name="l04523"></a><span class="lineno"> 4523</span>&#160;`executable`    | name of the &quot;executable&quot; to use in the WSDL definitions/service/port/address/\@location</div><div class="line"><a name="l04524"></a><span class="lineno"> 4524</span>&#160;</div><div class="line"><a name="l04525"></a><span class="lineno"> 4525</span>&#160;The service `name` and `namespace` properties are required in order to generate</div><div class="line"><a name="l04526"></a><span class="lineno"> 4526</span>&#160;a valid WSDL with soapcpp2.  The other properties are optional.</div><div class="line"><a name="l04527"></a><span class="lineno"> 4527</span>&#160;</div><div class="line"><a name="l04528"></a><span class="lineno"> 4528</span>&#160;The `style` and `encoding` property defaults are changed with</div><div class="line"><a name="l04529"></a><span class="lineno"> 4529</span>&#160;&lt;b&gt;`soapcpp2 -e`&lt;/b&gt; option &lt;b&gt;`-e`&lt;/b&gt; to `rpc` and `encoded`, respectively.</div><div class="line"><a name="l04530"></a><span class="lineno"> 4530</span>&#160;</div><div class="line"><a name="l04531"></a><span class="lineno"> 4531</span>&#160;The `protocol` property is `SOAP` by default (SOAP 1.1).  Protocol property</div><div class="line"><a name="l04532"></a><span class="lineno"> 4532</span>&#160;values are:</div><div class="line"><a name="l04533"></a><span class="lineno"> 4533</span>&#160;</div><div class="line"><a name="l04534"></a><span class="lineno"> 4534</span>&#160;protocol value | description</div><div class="line"><a name="l04535"></a><span class="lineno"> 4535</span>&#160;-------------- | -----------</div><div class="line"><a name="l04536"></a><span class="lineno"> 4536</span>&#160;`SOAP`         | SOAP transport, supporting both SOAP 1.1 and 1.2</div><div class="line"><a name="l04537"></a><span class="lineno"> 4537</span>&#160;`SOAP1.1`      | SOAP 1.1 transport (same as `soapcpp2 -1`)</div><div class="line"><a name="l04538"></a><span class="lineno"> 4538</span>&#160;`SOAP1.2`      | SOAP 1.2 transport (same as `soapcpp2 -2`)</div><div class="line"><a name="l04539"></a><span class="lineno"> 4539</span>&#160;`SOAP-GET`     | one-way SOAP 1.1 or 1.2 with HTTP GET</div><div class="line"><a name="l04540"></a><span class="lineno"> 4540</span>&#160;`SOAP1.1-GET`  | one-way SOAP 1.1 with HTTP GET</div><div class="line"><a name="l04541"></a><span class="lineno"> 4541</span>&#160;`SOAP1.2-GET`  | one-way SOAP 1.2 with HTTP GET</div><div class="line"><a name="l04542"></a><span class="lineno"> 4542</span>&#160;`HTTP`         | non-SOAP REST protocol with HTTP POST</div><div class="line"><a name="l04543"></a><span class="lineno"> 4543</span>&#160;`POST`         | non-SOAP REST protocol with HTTP POST</div><div class="line"><a name="l04544"></a><span class="lineno"> 4544</span>&#160;`GET`          | non-SOAP REST protocol with HTTP GET</div><div class="line"><a name="l04545"></a><span class="lineno"> 4545</span>&#160;`PUT`          | non-SOAP REST protocol with HTTP PUT</div><div class="line"><a name="l04546"></a><span class="lineno"> 4546</span>&#160;`DELETE`       | non-SOAP REST protocol with HTTP DELETE</div><div class="line"><a name="l04547"></a><span class="lineno"> 4547</span>&#160;</div><div class="line"><a name="l04548"></a><span class="lineno"> 4548</span>&#160;You can bind service operations to the WSDL namespace of a service by using the</div><div class="line"><a name="l04549"></a><span class="lineno"> 4549</span>&#160;namespace prefix as part of the identifier name of the function that defines</div><div class="line"><a name="l04550"></a><span class="lineno"> 4550</span>&#160;the service operation:</div><div class="line"><a name="l04551"></a><span class="lineno"> 4551</span>&#160;</div><div class="line"><a name="l04552"></a><span class="lineno"> 4552</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04553"></a><span class="lineno"> 4553</span>&#160;    int prefix__func(arg1, arg2, ..., argn, result);</div><div class="line"><a name="l04554"></a><span class="lineno"> 4554</span>&#160;~~~</div><div class="line"><a name="l04555"></a><span class="lineno"> 4555</span>&#160;</div><div class="line"><a name="l04556"></a><span class="lineno"> 4556</span>&#160;You can override the `port` endpoint URL at runtime in the auto-generated</div><div class="line"><a name="l04557"></a><span class="lineno"> 4557</span>&#160;`soap_call_prefix__func` service call (C/C++ client side) and in the C++ proxy</div><div class="line"><a name="l04558"></a><span class="lineno"> 4558</span>&#160;class service call.</div><div class="line"><a name="l04559"></a><span class="lineno"> 4559</span>&#160;</div><div class="line"><a name="l04560"></a><span class="lineno"> 4560</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l04561"></a><span class="lineno"> 4561</span>&#160;</div><div class="line"><a name="l04562"></a><span class="lineno"> 4562</span>&#160;Service method directives                                        {#directives-2}</div><div class="line"><a name="l04563"></a><span class="lineno"> 4563</span>&#160;-------------------------</div><div class="line"><a name="l04564"></a><span class="lineno"> 4564</span>&#160;</div><div class="line"><a name="l04565"></a><span class="lineno"> 4565</span>&#160;Service properties are applicable to a service and to all of its operations.</div><div class="line"><a name="l04566"></a><span class="lineno"> 4566</span>&#160;Service method directives are specifically applicable to a service operation.</div><div class="line"><a name="l04567"></a><span class="lineno"> 4567</span>&#160;</div><div class="line"><a name="l04568"></a><span class="lineno"> 4568</span>&#160;A service method directive is of the form:</div><div class="line"><a name="l04569"></a><span class="lineno"> 4569</span>&#160;</div><div class="line"><a name="l04570"></a><span class="lineno"> 4570</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04571"></a><span class="lineno"> 4571</span>&#160;    //gsoap &lt;prefix&gt; service method-&lt;property&gt;: &lt;method&gt; &lt;value&gt;</div><div class="line"><a name="l04572"></a><span class="lineno"> 4572</span>&#160;~~~</div><div class="line"><a name="l04573"></a><span class="lineno"> 4573</span>&#160;</div><div class="line"><a name="l04574"></a><span class="lineno"> 4574</span>&#160;where `&lt;prefix&gt;` is the XML namespace prefix of a service binding and</div><div class="line"><a name="l04575"></a><span class="lineno"> 4575</span>&#160;`&lt;method&gt;` is the unqualified name of a service operation.  The `&lt;property&gt;`</div><div class="line"><a name="l04576"></a><span class="lineno"> 4576</span>&#160;and `&lt;value&gt;` fields are one of the following:</div><div class="line"><a name="l04577"></a><span class="lineno"> 4577</span>&#160;</div><div class="line"><a name="l04578"></a><span class="lineno"> 4578</span>&#160;method property             | value</div><div class="line"><a name="l04579"></a><span class="lineno"> 4579</span>&#160;--------------------------- | -----</div><div class="line"><a name="l04580"></a><span class="lineno"> 4580</span>&#160;`method-documentation`      | text describing the service operation</div><div class="line"><a name="l04581"></a><span class="lineno"> 4581</span>&#160;`method`                    | an alias for the `method-documentation` property</div><div class="line"><a name="l04582"></a><span class="lineno"> 4582</span>&#160;`method-action`             | `&quot;&quot;` or URI SOAPAction HTTP header, or URL query string for REST protocols</div><div class="line"><a name="l04583"></a><span class="lineno"> 4583</span>&#160;`method-input-action`       | `&quot;&quot;` or URI SOAPAction HTTP header of service request messages</div><div class="line"><a name="l04584"></a><span class="lineno"> 4584</span>&#160;`method-output-action`      | `&quot;&quot;` or URI SOAPAction HTTP header of service response messages</div><div class="line"><a name="l04585"></a><span class="lineno"> 4585</span>&#160;`method-fault-action`       | `&quot;&quot;` or URI SOAPAction HTTP header of service fault messages</div><div class="line"><a name="l04586"></a><span class="lineno"> 4586</span>&#160;`method-header-part`        | member name of the `SOAP_ENV__Header` struct used in SOAP Header</div><div class="line"><a name="l04587"></a><span class="lineno"> 4587</span>&#160;`method-input-header-part`  | member name of the `SOAP_ENV__Header` struct used in SOAP Headers of requests</div><div class="line"><a name="l04588"></a><span class="lineno"> 4588</span>&#160;`method-output-header-part` | member name of the `SOAP_ENV__Header` struct used in SOAP Headers of responses</div><div class="line"><a name="l04589"></a><span class="lineno"> 4589</span>&#160;`method-fault`              | type name of a struct or class member used in `SOAP_ENV__Details` struct</div><div class="line"><a name="l04590"></a><span class="lineno"> 4590</span>&#160;`method-mime-type`          | REST content type or SOAP MIME attachment content type(s)</div><div class="line"><a name="l04591"></a><span class="lineno"> 4591</span>&#160;`method-input-mime-type`    | REST content type or SOAP MIME attachment content type(s) of request message</div><div class="line"><a name="l04592"></a><span class="lineno"> 4592</span>&#160;`method-output-mime-type`   | REST content type or SOAP MIME attachment content type(s) of response message</div><div class="line"><a name="l04593"></a><span class="lineno"> 4593</span>&#160;`method-style`              | `document` or `rpc`</div><div class="line"><a name="l04594"></a><span class="lineno"> 4594</span>&#160;`method-encoding`           | `literal`, `encoded`, or a custom URI for encodingStyle of messages</div><div class="line"><a name="l04595"></a><span class="lineno"> 4595</span>&#160;`method-response-encoding`  | `literal`, `encoded`, or a custom URI for encodingStyle of response messages</div><div class="line"><a name="l04596"></a><span class="lineno"> 4596</span>&#160;`method-protocol`           | SOAP or REST, see [service directives](#directives-1)</div><div class="line"><a name="l04597"></a><span class="lineno"> 4597</span>&#160;</div><div class="line"><a name="l04598"></a><span class="lineno"> 4598</span>&#160;The `method-header-part` properties can be repeated for a service operation to</div><div class="line"><a name="l04599"></a><span class="lineno"> 4599</span>&#160;declare multiple SOAP Header parts that the service operation requires.  You</div><div class="line"><a name="l04600"></a><span class="lineno"> 4600</span>&#160;can use `method-input-header-part` and `method-output-header-part` to</div><div class="line"><a name="l04601"></a><span class="lineno"> 4601</span>&#160;differentiate between request and response messages.</div><div class="line"><a name="l04602"></a><span class="lineno"> 4602</span>&#160;</div><div class="line"><a name="l04603"></a><span class="lineno"> 4603</span>&#160;The `method-fault` property can be repeated for a service operation to declare</div><div class="line"><a name="l04604"></a><span class="lineno"> 4604</span>&#160;multiple faults that the service operation may return.</div><div class="line"><a name="l04605"></a><span class="lineno"> 4605</span>&#160;</div><div class="line"><a name="l04606"></a><span class="lineno"> 4606</span>&#160;The `method-action` property serves two purposes:</div><div class="line"><a name="l04607"></a><span class="lineno"> 4607</span>&#160;</div><div class="line"><a name="l04608"></a><span class="lineno"> 4608</span>&#160;-# To set the SOAPAction header for SOAP protocols, i.e. sets the</div><div class="line"><a name="l04609"></a><span class="lineno"> 4609</span>&#160;   definitions/binding/operation/SOAP:operation/\@soapAction.</div><div class="line"><a name="l04610"></a><span class="lineno"> 4610</span>&#160;</div><div class="line"><a name="l04611"></a><span class="lineno"> 4611</span>&#160;-# To set the URL query string for endpoints with REST protocols, i.e. sets the</div><div class="line"><a name="l04612"></a><span class="lineno"> 4612</span>&#160;   definitions/binding/operation/HTTP:operation/\@location, which specifies</div><div class="line"><a name="l04613"></a><span class="lineno"> 4613</span>&#160;   a URL query string (starts with a `?`) to complete the service endpoint URL</div><div class="line"><a name="l04614"></a><span class="lineno"> 4614</span>&#160;   or extends the endpoint URL with a local path (starts with a `/`).</div><div class="line"><a name="l04615"></a><span class="lineno"> 4615</span>&#160;</div><div class="line"><a name="l04616"></a><span class="lineno"> 4616</span>&#160;Use `method-input-action` and `method-output-action` to differentiate the</div><div class="line"><a name="l04617"></a><span class="lineno"> 4617</span>&#160;SOAPAction between SOAP request and response messages.</div><div class="line"><a name="l04618"></a><span class="lineno"> 4618</span>&#160;</div><div class="line"><a name="l04619"></a><span class="lineno"> 4619</span>&#160;You can always override the port endpoint URL and action values at runtime in</div><div class="line"><a name="l04620"></a><span class="lineno"> 4620</span>&#160;the auto-generated `soap_call_prefix__func` service call (C/C++ client side)</div><div class="line"><a name="l04621"></a><span class="lineno"> 4621</span>&#160;and in the auto-generated C++ proxy class service calls.  A runtime NULL</div><div class="line"><a name="l04622"></a><span class="lineno"> 4622</span>&#160;endpoint URL and/or action uses the defaults set by these directives.</div><div class="line"><a name="l04623"></a><span class="lineno"> 4623</span>&#160;</div><div class="line"><a name="l04624"></a><span class="lineno"> 4624</span>&#160;The `method-mime-type` property serves two purposes:</div><div class="line"><a name="l04625"></a><span class="lineno"> 4625</span>&#160;</div><div class="line"><a name="l04626"></a><span class="lineno"> 4626</span>&#160;-# To set the type of MIME/MTOM attachments used with SOAP protocols.  Multiple</div><div class="line"><a name="l04627"></a><span class="lineno"> 4627</span>&#160;   attachment types can be declared for a SOAP service operation, i.e. adds</div><div class="line"><a name="l04628"></a><span class="lineno"> 4628</span>&#160;   definitions/binding/operation/input/MIME:multipartRelated/MIME:part/MIME:content/\@type</div><div class="line"><a name="l04629"></a><span class="lineno"> 4629</span>&#160;   for each type specified.</div><div class="line"><a name="l04630"></a><span class="lineno"> 4630</span>&#160;</div><div class="line"><a name="l04631"></a><span class="lineno"> 4631</span>&#160;-# To set the MIME type of a REST operation.  This replaces XML declared in</div><div class="line"><a name="l04632"></a><span class="lineno"> 4632</span>&#160;   WSDL by definitions/binding/operation/(input|output)/MIME:mimeXml with</div><div class="line"><a name="l04633"></a><span class="lineno"> 4633</span>&#160;   MIME:content/\@type.  Use `application/x-www-form-urlencoded` with REST POST</div><div class="line"><a name="l04634"></a><span class="lineno"> 4634</span>&#160;   and PUT protocols to send encoded form data automatically instead of XML.</div><div class="line"><a name="l04635"></a><span class="lineno"> 4635</span>&#160;   Only primitive type values can be transmitted with form data, such as</div><div class="line"><a name="l04636"></a><span class="lineno"> 4636</span>&#160;   numbers and strings, i.e. only types that are legal to use as</div><div class="line"><a name="l04637"></a><span class="lineno"> 4637</span>&#160;   [attributes members](#toxsd9-5).  </div><div class="line"><a name="l04638"></a><span class="lineno"> 4638</span>&#160;</div><div class="line"><a name="l04639"></a><span class="lineno"> 4639</span>&#160;Use `method-input-mime-type` and `method-output-mime-type` to differentiate the</div><div class="line"><a name="l04640"></a><span class="lineno"> 4640</span>&#160;attachment types between request and response messages.</div><div class="line"><a name="l04641"></a><span class="lineno"> 4641</span>&#160;</div><div class="line"><a name="l04642"></a><span class="lineno"> 4642</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l04643"></a><span class="lineno"> 4643</span>&#160;</div><div class="line"><a name="l04644"></a><span class="lineno"> 4644</span>&#160;Schema directives                                                {#directives-3}</div><div class="line"><a name="l04645"></a><span class="lineno"> 4645</span>&#160;-----------------</div><div class="line"><a name="l04646"></a><span class="lineno"> 4646</span>&#160;</div><div class="line"><a name="l04647"></a><span class="lineno"> 4647</span>&#160;A schema directive is of the form:</div><div class="line"><a name="l04648"></a><span class="lineno"> 4648</span>&#160;</div><div class="line"><a name="l04649"></a><span class="lineno"> 4649</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04650"></a><span class="lineno"> 4650</span>&#160;    //gsoap &lt;prefix&gt; schema &lt;property&gt;: &lt;value&gt;</div><div class="line"><a name="l04651"></a><span class="lineno"> 4651</span>&#160;~~~</div><div class="line"><a name="l04652"></a><span class="lineno"> 4652</span>&#160;</div><div class="line"><a name="l04653"></a><span class="lineno"> 4653</span>&#160;where `&lt;prefix&gt;` is the XML namespace prefix of a schema.  The `&lt;property&gt;` and</div><div class="line"><a name="l04654"></a><span class="lineno"> 4654</span>&#160;`&lt;value&gt;` fields are one of the following:</div><div class="line"><a name="l04655"></a><span class="lineno"> 4655</span>&#160;</div><div class="line"><a name="l04656"></a><span class="lineno"> 4656</span>&#160;property        | value</div><div class="line"><a name="l04657"></a><span class="lineno"> 4657</span>&#160;--------------- | -----</div><div class="line"><a name="l04658"></a><span class="lineno"> 4658</span>&#160;`namespace`     | URI of the XSD targetNamespace</div><div class="line"><a name="l04659"></a><span class="lineno"> 4659</span>&#160;`namespace2`    | alternate URI pattern for the XSD namespace (i.e. URI is also accepted by the XML parser)</div><div class="line"><a name="l04660"></a><span class="lineno"> 4660</span>&#160;`import`        | URI of an imported namespace, as an alternative or in addition to `namespace`, adds `xsd:import` to the generated WSDL and XSD files</div><div class="line"><a name="l04661"></a><span class="lineno"> 4661</span>&#160;`form`          | `unqualified` (default) or `qualified` local element and attribute form defaults</div><div class="line"><a name="l04662"></a><span class="lineno"> 4662</span>&#160;`elementForm`   | `unqualified` (default) or `qualified` local element form default</div><div class="line"><a name="l04663"></a><span class="lineno"> 4663</span>&#160;`attributeForm` | `unqualified` (default) or `qualified` local attribute form default</div><div class="line"><a name="l04664"></a><span class="lineno"> 4664</span>&#160;`typed`         | `no` (default) or `yes` for serializers to add `xsi:type` attributes to XML</div><div class="line"><a name="l04665"></a><span class="lineno"> 4665</span>&#160;</div><div class="line"><a name="l04666"></a><span class="lineno"> 4666</span>&#160;To learn more about the local form defaults, see [qualified and unqualified members.](#toxsd9-6)</div><div class="line"><a name="l04667"></a><span class="lineno"> 4667</span>&#160;</div><div class="line"><a name="l04668"></a><span class="lineno"> 4668</span>&#160;The `namespace2` URI is a pattern with `*` matching any sequence of characters</div><div class="line"><a name="l04669"></a><span class="lineno"> 4669</span>&#160;and `-` matching any character.  This pattern instructs the XML parser and validator</div><div class="line"><a name="l04670"></a><span class="lineno"> 4670</span>&#160;to also accept the URI pattern as a valid namespace for the specified `&lt;prefix&gt;`.</div><div class="line"><a name="l04671"></a><span class="lineno"> 4671</span>&#160;</div><div class="line"><a name="l04672"></a><span class="lineno"> 4672</span>&#160;The `typed` property is implicitly `yes` when &lt;b&gt;`soapcpp2 -t`&lt;/b&gt; option &lt;b&gt;`-t`&lt;/b&gt; is used.</div><div class="line"><a name="l04673"></a><span class="lineno"> 4673</span>&#160;</div><div class="line"><a name="l04674"></a><span class="lineno"> 4674</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l04675"></a><span class="lineno"> 4675</span>&#160;</div><div class="line"><a name="l04676"></a><span class="lineno"> 4676</span>&#160;Schema type directives                                           {#directives-4}</div><div class="line"><a name="l04677"></a><span class="lineno"> 4677</span>&#160;----------------------</div><div class="line"><a name="l04678"></a><span class="lineno"> 4678</span>&#160;</div><div class="line"><a name="l04679"></a><span class="lineno"> 4679</span>&#160;A schema type directive is of the form:</div><div class="line"><a name="l04680"></a><span class="lineno"> 4680</span>&#160;</div><div class="line"><a name="l04681"></a><span class="lineno"> 4681</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04682"></a><span class="lineno"> 4682</span>&#160;    //gsoap &lt;prefix&gt; schema type-&lt;property&gt;: &lt;name&gt; &lt;value&gt;</div><div class="line"><a name="l04683"></a><span class="lineno"> 4683</span>&#160;    //gsoap &lt;prefix&gt; schema type-&lt;property&gt;: &lt;name&gt;::&lt;member&gt; &lt;value&gt;</div><div class="line"><a name="l04684"></a><span class="lineno"> 4684</span>&#160;~~~</div><div class="line"><a name="l04685"></a><span class="lineno"> 4685</span>&#160;</div><div class="line"><a name="l04686"></a><span class="lineno"> 4686</span>&#160;where `&lt;prefix&gt;` is the XML namespace prefix of a schema and `&lt;name&gt;` is an</div><div class="line"><a name="l04687"></a><span class="lineno"> 4687</span>&#160;unqualified name of a C/C++ type, and the optional `&lt;member&gt;` is a class/struct</div><div class="line"><a name="l04688"></a><span class="lineno"> 4688</span>&#160;members or enum constant.</div><div class="line"><a name="l04689"></a><span class="lineno"> 4689</span>&#160;</div><div class="line"><a name="l04690"></a><span class="lineno"> 4690</span>&#160;You can describe a type with one of the following:</div><div class="line"><a name="l04691"></a><span class="lineno"> 4691</span>&#160;</div><div class="line"><a name="l04692"></a><span class="lineno"> 4692</span>&#160;type property        | value</div><div class="line"><a name="l04693"></a><span class="lineno"> 4693</span>&#160;-------------------- | -----</div><div class="line"><a name="l04694"></a><span class="lineno"> 4694</span>&#160;`type-documentation` | text describing the schema type</div><div class="line"><a name="l04695"></a><span class="lineno"> 4695</span>&#160;`type`               | an alias for the `type-documentation` property</div><div class="line"><a name="l04696"></a><span class="lineno"> 4696</span>&#160;</div><div class="line"><a name="l04697"></a><span class="lineno"> 4697</span>&#160;For example, you can add a description to an enumeration:</div><div class="line"><a name="l04698"></a><span class="lineno"> 4698</span>&#160;</div><div class="line"><a name="l04699"></a><span class="lineno"> 4699</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04700"></a><span class="lineno"> 4700</span>&#160;    //gsoap ns schema type: Vowels The letters A, E, I, O, U, and sometimes Y</div><div class="line"><a name="l04701"></a><span class="lineno"> 4701</span>&#160;    //gsoap ns schema type: Vowels::Y A vowel, sometimes</div><div class="line"><a name="l04702"></a><span class="lineno"> 4702</span>&#160;    enum class ns__Vowels : char { A = &#39;A&#39;, E = &#39;E&#39;, I = &#39;I&#39;, O = &#39;O&#39;, U = &#39;U&#39;, Y = &#39;Y&#39; };</div><div class="line"><a name="l04703"></a><span class="lineno"> 4703</span>&#160;~~~</div><div class="line"><a name="l04704"></a><span class="lineno"> 4704</span>&#160;</div><div class="line"><a name="l04705"></a><span class="lineno"> 4705</span>&#160;This documented enumeration maps to a simpleType restriction of &lt;i&gt;`xsd:string`&lt;/i&gt; in</div><div class="line"><a name="l04706"></a><span class="lineno"> 4706</span>&#160;the soapcpp2-generated schema:</div><div class="line"><a name="l04707"></a><span class="lineno"> 4707</span>&#160;</div><div class="line"><a name="l04708"></a><span class="lineno"> 4708</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l04709"></a><span class="lineno"> 4709</span>&#160;~~~{.xml}</div><div class="line"><a name="l04710"></a><span class="lineno"> 4710</span>&#160;    &lt;simpleType name=&quot;Vowels&quot;&gt;</div><div class="line"><a name="l04711"></a><span class="lineno"> 4711</span>&#160;      &lt;annotation&gt;</div><div class="line"><a name="l04712"></a><span class="lineno"> 4712</span>&#160;        &lt;documentation&gt;The letters A, E, I, O, U, and sometimes Y&lt;/documentation&gt;</div><div class="line"><a name="l04713"></a><span class="lineno"> 4713</span>&#160;      &lt;/annotation&gt;</div><div class="line"><a name="l04714"></a><span class="lineno"> 4714</span>&#160;      &lt;restriction base=&quot;xsd:string&quot;&gt;</div><div class="line"><a name="l04715"></a><span class="lineno"> 4715</span>&#160;        &lt;enumeration value=&quot;A&quot;/&gt;</div><div class="line"><a name="l04716"></a><span class="lineno"> 4716</span>&#160;        &lt;enumeration value=&quot;E&quot;/&gt;</div><div class="line"><a name="l04717"></a><span class="lineno"> 4717</span>&#160;        &lt;enumeration value=&quot;I&quot;/&gt;</div><div class="line"><a name="l04718"></a><span class="lineno"> 4718</span>&#160;        &lt;enumeration value=&quot;O&quot;/&gt;</div><div class="line"><a name="l04719"></a><span class="lineno"> 4719</span>&#160;        &lt;enumeration value=&quot;U&quot;/&gt;</div><div class="line"><a name="l04720"></a><span class="lineno"> 4720</span>&#160;        &lt;enumeration value=&quot;Y&quot;&gt;</div><div class="line"><a name="l04721"></a><span class="lineno"> 4721</span>&#160;          &lt;annotation&gt;</div><div class="line"><a name="l04722"></a><span class="lineno"> 4722</span>&#160;            &lt;documentation&gt;A vowel, sometimes&lt;/documentation&gt;</div><div class="line"><a name="l04723"></a><span class="lineno"> 4723</span>&#160;          &lt;/annotation&gt;</div><div class="line"><a name="l04724"></a><span class="lineno"> 4724</span>&#160;        &lt;enumeration/&gt;</div><div class="line"><a name="l04725"></a><span class="lineno"> 4725</span>&#160;      &lt;/restriction&gt;</div><div class="line"><a name="l04726"></a><span class="lineno"> 4726</span>&#160;    &lt;/simpleType&gt;</div><div class="line"><a name="l04727"></a><span class="lineno"> 4727</span>&#160;~~~</div><div class="line"><a name="l04728"></a><span class="lineno"> 4728</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l04729"></a><span class="lineno"> 4729</span>&#160;</div><div class="line"><a name="l04730"></a><span class="lineno"> 4730</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l04731"></a><span class="lineno"> 4731</span>&#160;</div><div class="line"><a name="l04732"></a><span class="lineno"> 4732</span>&#160;Serialization rules                                                     {#rules}</div><div class="line"><a name="l04733"></a><span class="lineno"> 4733</span>&#160;===================</div><div class="line"><a name="l04734"></a><span class="lineno"> 4734</span>&#160;</div><div class="line"><a name="l04735"></a><span class="lineno"> 4735</span>&#160;A presentation on XML data bindings is not complete without discussing the</div><div class="line"><a name="l04736"></a><span class="lineno"> 4736</span>&#160;serialization rules and options that put your data in XML on the wire or store</div><div class="line"><a name="l04737"></a><span class="lineno"> 4737</span>&#160;it a file or buffer.</div><div class="line"><a name="l04738"></a><span class="lineno"> 4738</span>&#160;</div><div class="line"><a name="l04739"></a><span class="lineno"> 4739</span>&#160;There are several options to choose from to serialize data in XML.  The choice</div><div class="line"><a name="l04740"></a><span class="lineno"> 4740</span>&#160;depends on the use of the SOAP protocol or if SOAP is not required.  The wsdl2h</div><div class="line"><a name="l04741"></a><span class="lineno"> 4741</span>&#160;tool automates this for you by taking the WSDL transport bindings into account</div><div class="line"><a name="l04742"></a><span class="lineno"> 4742</span>&#160;when generating the service functions in C and C++ that use SOAP or REST.</div><div class="line"><a name="l04743"></a><span class="lineno"> 4743</span>&#160;</div><div class="line"><a name="l04744"></a><span class="lineno"> 4744</span>&#160;The gSOAP tools are not limited to SOAP.  The tools implement generic XML data</div><div class="line"><a name="l04745"></a><span class="lineno"> 4745</span>&#160;bindings for SOAP, REST, and other uses of XML.  So you can read and write XML</div><div class="line"><a name="l04746"></a><span class="lineno"> 4746</span>&#160;using the serializing [operations on classes and structs](#toxsd9-14).</div><div class="line"><a name="l04747"></a><span class="lineno"> 4747</span>&#160;</div><div class="line"><a name="l04748"></a><span class="lineno"> 4748</span>&#160;The following sections briefly explain the serialization rules with respect to</div><div class="line"><a name="l04749"></a><span class="lineno"> 4749</span>&#160;the SOAP protocol for XML Web services.  A basic understanding of the SOAP</div><div class="line"><a name="l04750"></a><span class="lineno"> 4750</span>&#160;protocol is useful when developing client and server applications that must</div><div class="line"><a name="l04751"></a><span class="lineno"> 4751</span>&#160;interoperate with other SOAP applications.</div><div class="line"><a name="l04752"></a><span class="lineno"> 4752</span>&#160;</div><div class="line"><a name="l04753"></a><span class="lineno"> 4753</span>&#160;SOAP/REST Web service client and service operations are represented as</div><div class="line"><a name="l04754"></a><span class="lineno"> 4754</span>&#160;functions in your interface header file with the data binding interface for</div><div class="line"><a name="l04755"></a><span class="lineno"> 4755</span>&#160;soapcpp2.  The soapcpp2 tool will translate these function to client-side</div><div class="line"><a name="l04756"></a><span class="lineno"> 4756</span>&#160;service invocation calls and server-side service operation dispatchers.</div><div class="line"><a name="l04757"></a><span class="lineno"> 4757</span>&#160;</div><div class="line"><a name="l04758"></a><span class="lineno"> 4758</span>&#160;A discussion of SOAP clients and servers is beyond the scope of this article.</div><div class="line"><a name="l04759"></a><span class="lineno"> 4759</span>&#160;However, the SOAP options discussed here also apply to SOAP client and server</div><div class="line"><a name="l04760"></a><span class="lineno"> 4760</span>&#160;development.</div><div class="line"><a name="l04761"></a><span class="lineno"> 4761</span>&#160;</div><div class="line"><a name="l04762"></a><span class="lineno"> 4762</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l04763"></a><span class="lineno"> 4763</span>&#160;</div><div class="line"><a name="l04764"></a><span class="lineno"> 4764</span>&#160;SOAP document versus rpc style                                        {#doc-rpc}</div><div class="line"><a name="l04765"></a><span class="lineno"> 4765</span>&#160;------------------------------</div><div class="line"><a name="l04766"></a><span class="lineno"> 4766</span>&#160;</div><div class="line"><a name="l04767"></a><span class="lineno"> 4767</span>&#160;The `wsdl:binding/soap:binding/@style` attribute in the &lt;i&gt;`&lt;wsdl:binding&gt;`&lt;/i&gt;</div><div class="line"><a name="l04768"></a><span class="lineno"> 4768</span>&#160;section of a WSDL is either &quot;document&quot; or &quot;rpc&quot;.  The &quot;rpc&quot; style refers to</div><div class="line"><a name="l04769"></a><span class="lineno"> 4769</span>&#160;SOAP RPC (Remote Procedure Call), which is more restrictive than the &quot;document&quot;</div><div class="line"><a name="l04770"></a><span class="lineno"> 4770</span>&#160;style by requiring one XML element in the SOAP Body to act as the procedure</div><div class="line"><a name="l04771"></a><span class="lineno"> 4771</span>&#160;name with XML subelements as its parameters.</div><div class="line"><a name="l04772"></a><span class="lineno"> 4772</span>&#160;</div><div class="line"><a name="l04773"></a><span class="lineno"> 4773</span>&#160;For example, the following directives in the interface header file for soapcpp2</div><div class="line"><a name="l04774"></a><span class="lineno"> 4774</span>&#160;declare that `DBupdate` is a SOAP RPC encoding service method:</div><div class="line"><a name="l04775"></a><span class="lineno"> 4775</span>&#160;</div><div class="line"><a name="l04776"></a><span class="lineno"> 4776</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04777"></a><span class="lineno"> 4777</span>&#160;    //gsoap ns service namespace:       urn:DB</div><div class="line"><a name="l04778"></a><span class="lineno"> 4778</span>&#160;    //gsoap ns service method-protocol: DBupdate SOAP</div><div class="line"><a name="l04779"></a><span class="lineno"> 4779</span>&#160;    //gsoap ns service method-style:    DBupdate rpc</div><div class="line"><a name="l04780"></a><span class="lineno"> 4780</span>&#160;    int ns__DBupdate(...);</div><div class="line"><a name="l04781"></a><span class="lineno"> 4781</span>&#160;~~~</div><div class="line"><a name="l04782"></a><span class="lineno"> 4782</span>&#160;</div><div class="line"><a name="l04783"></a><span class="lineno"> 4783</span>&#160;The XML payload has a SOAP envelope, optional SOAP header, and a SOAP body with</div><div class="line"><a name="l04784"></a><span class="lineno"> 4784</span>&#160;one element representing the operation with the parameters as subelements:</div><div class="line"><a name="l04785"></a><span class="lineno"> 4785</span>&#160;</div><div class="line"><a name="l04786"></a><span class="lineno"> 4786</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l04787"></a><span class="lineno"> 4787</span>&#160;~~~{.xml}</div><div class="line"><a name="l04788"></a><span class="lineno"> 4788</span>&#160;    &lt;SOAP-ENV:Envelope</div><div class="line"><a name="l04789"></a><span class="lineno"> 4789</span>&#160;      xmlns:SOAP-ENV=&quot;http://schemas.xmlsoap.org/soap/envelope/&quot;</div><div class="line"><a name="l04790"></a><span class="lineno"> 4790</span>&#160;      xmlns:SOAP-ENC=&quot;http://schemas.xmlsoap.org/soap/encoding/&quot;</div><div class="line"><a name="l04791"></a><span class="lineno"> 4791</span>&#160;      xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;</div><div class="line"><a name="l04792"></a><span class="lineno"> 4792</span>&#160;      xmlns:xsd=&quot;http://www.w3.org/2001/XMLSchema&quot;</div><div class="line"><a name="l04793"></a><span class="lineno"> 4793</span>&#160;      xmlsn:ns=&quot;urn:DB&quot;&gt;</div><div class="line"><a name="l04794"></a><span class="lineno"> 4794</span>&#160;      &lt;SOAP-ENV:Body&gt;</div><div class="line"><a name="l04795"></a><span class="lineno"> 4795</span>&#160;        &lt;ns:DBupdate&gt;</div><div class="line"><a name="l04796"></a><span class="lineno"> 4796</span>&#160;          ...</div><div class="line"><a name="l04797"></a><span class="lineno"> 4797</span>&#160;        &lt;/ns:DBupdate&gt;</div><div class="line"><a name="l04798"></a><span class="lineno"> 4798</span>&#160;      &lt;/SOAP-ENV:Body&gt;</div><div class="line"><a name="l04799"></a><span class="lineno"> 4799</span>&#160;    &lt;/SOAP-ENV:Envelope&gt;</div><div class="line"><a name="l04800"></a><span class="lineno"> 4800</span>&#160;~~~</div><div class="line"><a name="l04801"></a><span class="lineno"> 4801</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l04802"></a><span class="lineno"> 4802</span>&#160;</div><div class="line"><a name="l04803"></a><span class="lineno"> 4803</span>&#160;The &quot;document&quot; style puts no restrictions on the SOAP Body content.  However, we</div><div class="line"><a name="l04804"></a><span class="lineno"> 4804</span>&#160;recommend that the first element&#39;s tag name in the SOAP Body should be unique</div><div class="line"><a name="l04805"></a><span class="lineno"> 4805</span>&#160;to each type of operation, so that the receiver can dispatch the operation</div><div class="line"><a name="l04806"></a><span class="lineno"> 4806</span>&#160;based on this element&#39;s tag name.  Alternatively, the HTTP URL path can be used</div><div class="line"><a name="l04807"></a><span class="lineno"> 4807</span>&#160;to specify the operation, or the HTTP action header can be used to dispatch</div><div class="line"><a name="l04808"></a><span class="lineno"> 4808</span>&#160;operations automatically on the server side (soapcpp2 options -a and -A).</div><div class="line"><a name="l04809"></a><span class="lineno"> 4809</span>&#160;</div><div class="line"><a name="l04810"></a><span class="lineno"> 4810</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l04811"></a><span class="lineno"> 4811</span>&#160;</div><div class="line"><a name="l04812"></a><span class="lineno"> 4812</span>&#160;SOAP literal versus encoding                                          {#lit-enc}</div><div class="line"><a name="l04813"></a><span class="lineno"> 4813</span>&#160;----------------------------</div><div class="line"><a name="l04814"></a><span class="lineno"> 4814</span>&#160;</div><div class="line"><a name="l04815"></a><span class="lineno"> 4815</span>&#160;The `wsdl:operation/soap:body/@use` attribute in the &lt;i&gt;`&lt;wsdl:binding&gt;`&lt;/i&gt; section</div><div class="line"><a name="l04816"></a><span class="lineno"> 4816</span>&#160;of a WSDL is either &quot;literal&quot; or &quot;encoded&quot;.  The &quot;encoded&quot; use refers to the</div><div class="line"><a name="l04817"></a><span class="lineno"> 4817</span>&#160;SOAP encoding rules that support id-ref multi-referenced elements to serialize</div><div class="line"><a name="l04818"></a><span class="lineno"> 4818</span>&#160;data as graphs.</div><div class="line"><a name="l04819"></a><span class="lineno"> 4819</span>&#160;</div><div class="line"><a name="l04820"></a><span class="lineno"> 4820</span>&#160;SOAP encoding is very useful if the data internally forms a graph (including</div><div class="line"><a name="l04821"></a><span class="lineno"> 4821</span>&#160;cycles) and we want the graph to be serialized in XML in a format that ensures</div><div class="line"><a name="l04822"></a><span class="lineno"> 4822</span>&#160;that its structure is preserved.  In that case, SOAP 1.2 encoding is the best</div><div class="line"><a name="l04823"></a><span class="lineno"> 4823</span>&#160;option.</div><div class="line"><a name="l04824"></a><span class="lineno"> 4824</span>&#160;</div><div class="line"><a name="l04825"></a><span class="lineno"> 4825</span>&#160;SOAP encoding also adds encoding rules for [SOAP arrays](#toxsd10) to serialize</div><div class="line"><a name="l04826"></a><span class="lineno"> 4826</span>&#160;multi-dimensional arrays.  The use of XML attributes to exchange XML data in</div><div class="line"><a name="l04827"></a><span class="lineno"> 4827</span>&#160;SOAP encoding is not permitted.  The only attributes permitted are the standard</div><div class="line"><a name="l04828"></a><span class="lineno"> 4828</span>&#160;XSD attributes, SOAP encoding attributes (such as for arrays), and id-ref.</div><div class="line"><a name="l04829"></a><span class="lineno"> 4829</span>&#160;</div><div class="line"><a name="l04830"></a><span class="lineno"> 4830</span>&#160;For example, the following directives in the interface header file for soapcpp2</div><div class="line"><a name="l04831"></a><span class="lineno"> 4831</span>&#160;declare that `DBupdate` is a SOAP RPC encoding service method:</div><div class="line"><a name="l04832"></a><span class="lineno"> 4832</span>&#160;</div><div class="line"><a name="l04833"></a><span class="lineno"> 4833</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04834"></a><span class="lineno"> 4834</span>&#160;    //gsoap ns service namespace:       urn:DB</div><div class="line"><a name="l04835"></a><span class="lineno"> 4835</span>&#160;    //gsoap ns service method-protocol: DBupdate SOAP</div><div class="line"><a name="l04836"></a><span class="lineno"> 4836</span>&#160;    //gsoap ns service method-style:    DBupdate rpc</div><div class="line"><a name="l04837"></a><span class="lineno"> 4837</span>&#160;    //gsoap ns service method-encoding: DBupdate encoded</div><div class="line"><a name="l04838"></a><span class="lineno"> 4838</span>&#160;    int ns__DBupdate(...);</div><div class="line"><a name="l04839"></a><span class="lineno"> 4839</span>&#160;~~~</div><div class="line"><a name="l04840"></a><span class="lineno"> 4840</span>&#160;</div><div class="line"><a name="l04841"></a><span class="lineno"> 4841</span>&#160;The XML payload has a SOAP envelope, optional SOAP header, and a SOAP body with</div><div class="line"><a name="l04842"></a><span class="lineno"> 4842</span>&#160;an encodingStyle attribute for SOAP 1.1 encoding and an element representing the</div><div class="line"><a name="l04843"></a><span class="lineno"> 4843</span>&#160;operation with parameters that are SOAP 1.1 encoded:</div><div class="line"><a name="l04844"></a><span class="lineno"> 4844</span>&#160;</div><div class="line"><a name="l04845"></a><span class="lineno"> 4845</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l04846"></a><span class="lineno"> 4846</span>&#160;~~~{.xml}</div><div class="line"><a name="l04847"></a><span class="lineno"> 4847</span>&#160;    &lt;SOAP-ENV:Envelope</div><div class="line"><a name="l04848"></a><span class="lineno"> 4848</span>&#160;      xmlns:SOAP-ENV=&quot;http://schemas.xmlsoap.org/soap/envelope/&quot;</div><div class="line"><a name="l04849"></a><span class="lineno"> 4849</span>&#160;      xmlns:SOAP-ENC=&quot;http://schemas.xmlsoap.org/soap/encoding/&quot;</div><div class="line"><a name="l04850"></a><span class="lineno"> 4850</span>&#160;      xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;</div><div class="line"><a name="l04851"></a><span class="lineno"> 4851</span>&#160;      xmlns:xsd=&quot;http://www.w3.org/2001/XMLSchema&quot;</div><div class="line"><a name="l04852"></a><span class="lineno"> 4852</span>&#160;      xmlsn:ns=&quot;urn:DB&quot;&gt;</div><div class="line"><a name="l04853"></a><span class="lineno"> 4853</span>&#160;      &lt;SOAP-ENV:Body SOAP-ENV:encodingStyle=&quot;http://schemas.xmlsoap.org/soap/encoding/&quot;&gt;</div><div class="line"><a name="l04854"></a><span class="lineno"> 4854</span>&#160;        &lt;ns:DBupdate&gt;</div><div class="line"><a name="l04855"></a><span class="lineno"> 4855</span>&#160;          &lt;records SOAP-ENC:arrayType=&quot;ns:record[3]&quot;&gt;</div><div class="line"><a name="l04856"></a><span class="lineno"> 4856</span>&#160;            &lt;item&gt;</div><div class="line"><a name="l04857"></a><span class="lineno"> 4857</span>&#160;              &lt;name href=&quot;#_1&quot;/&gt;</div><div class="line"><a name="l04858"></a><span class="lineno"> 4858</span>&#160;              &lt;SSN&gt;1234567890&lt;/SSN&gt;</div><div class="line"><a name="l04859"></a><span class="lineno"> 4859</span>&#160;            &lt;/item&gt;</div><div class="line"><a name="l04860"></a><span class="lineno"> 4860</span>&#160;            &lt;item&gt;</div><div class="line"><a name="l04861"></a><span class="lineno"> 4861</span>&#160;              &lt;name&gt;Jane&lt;/name&gt;</div><div class="line"><a name="l04862"></a><span class="lineno"> 4862</span>&#160;              &lt;SSN&gt;1987654320&lt;/SSN&gt;</div><div class="line"><a name="l04863"></a><span class="lineno"> 4863</span>&#160;            &lt;/item&gt;</div><div class="line"><a name="l04864"></a><span class="lineno"> 4864</span>&#160;            &lt;item&gt;</div><div class="line"><a name="l04865"></a><span class="lineno"> 4865</span>&#160;              &lt;name href=&quot;#_1&quot;/&gt;</div><div class="line"><a name="l04866"></a><span class="lineno"> 4866</span>&#160;              &lt;SSN&gt;2345678901&lt;/SSN&gt;</div><div class="line"><a name="l04867"></a><span class="lineno"> 4867</span>&#160;            &lt;/item&gt;</div><div class="line"><a name="l04868"></a><span class="lineno"> 4868</span>&#160;          &lt;/records&gt;</div><div class="line"><a name="l04869"></a><span class="lineno"> 4869</span>&#160;        &lt;/ns:DBupdate&gt;</div><div class="line"><a name="l04870"></a><span class="lineno"> 4870</span>&#160;        &lt;id id=&quot;_1&quot; xsi:type=&quot;xsd:string&quot;&gt;Joe&lt;/id&gt;</div><div class="line"><a name="l04871"></a><span class="lineno"> 4871</span>&#160;      &lt;/SOAP-ENV:Body&gt;</div><div class="line"><a name="l04872"></a><span class="lineno"> 4872</span>&#160;    &lt;/SOAP-ENV:Envelope&gt;</div><div class="line"><a name="l04873"></a><span class="lineno"> 4873</span>&#160;~~~</div><div class="line"><a name="l04874"></a><span class="lineno"> 4874</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l04875"></a><span class="lineno"> 4875</span>&#160;</div><div class="line"><a name="l04876"></a><span class="lineno"> 4876</span>&#160;In the XML fragment shown above the name &quot;Joe&quot; is shared by two records and the</div><div class="line"><a name="l04877"></a><span class="lineno"> 4877</span>&#160;string is referenced by SOAP 1.1 href and id attributes.</div><div class="line"><a name="l04878"></a><span class="lineno"> 4878</span>&#160;</div><div class="line"><a name="l04879"></a><span class="lineno"> 4879</span>&#160;While the soapcpp-generated serializers only introduce multi-referenced</div><div class="line"><a name="l04880"></a><span class="lineno"> 4880</span>&#160;elements in the payload when they are actually multi-referenced in the data</div><div class="line"><a name="l04881"></a><span class="lineno"> 4881</span>&#160;graph, other SOAP applications may render multi-referenced elements more</div><div class="line"><a name="l04882"></a><span class="lineno"> 4882</span>&#160;aggressively.  The example could also be rendered as:</div><div class="line"><a name="l04883"></a><span class="lineno"> 4883</span>&#160;</div><div class="line"><a name="l04884"></a><span class="lineno"> 4884</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l04885"></a><span class="lineno"> 4885</span>&#160;~~~{.xml}</div><div class="line"><a name="l04886"></a><span class="lineno"> 4886</span>&#160;    &lt;SOAP-ENV:Envelope</div><div class="line"><a name="l04887"></a><span class="lineno"> 4887</span>&#160;      xmlns:SOAP-ENV=&quot;http://schemas.xmlsoap.org/soap/envelope/&quot;</div><div class="line"><a name="l04888"></a><span class="lineno"> 4888</span>&#160;      xmlns:SOAP-ENC=&quot;http://schemas.xmlsoap.org/soap/encoding/&quot;</div><div class="line"><a name="l04889"></a><span class="lineno"> 4889</span>&#160;      xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;</div><div class="line"><a name="l04890"></a><span class="lineno"> 4890</span>&#160;      xmlns:xsd=&quot;http://www.w3.org/2001/XMLSchema&quot;</div><div class="line"><a name="l04891"></a><span class="lineno"> 4891</span>&#160;      xmlsn:ns=&quot;urn:DB&quot;&gt;</div><div class="line"><a name="l04892"></a><span class="lineno"> 4892</span>&#160;      &lt;SOAP-ENV:Body SOAP-ENV:encodingStyle=&quot;http://schemas.xmlsoap.org/soap/encoding/&quot;&gt;</div><div class="line"><a name="l04893"></a><span class="lineno"> 4893</span>&#160;        &lt;ns:DBupdate&gt;</div><div class="line"><a name="l04894"></a><span class="lineno"> 4894</span>&#160;          &lt;records SOAP-ENC:arrayType=&quot;ns:record[3]&quot;&gt;</div><div class="line"><a name="l04895"></a><span class="lineno"> 4895</span>&#160;            &lt;item href=&quot;#id1&quot;/&gt;</div><div class="line"><a name="l04896"></a><span class="lineno"> 4896</span>&#160;            &lt;item href=&quot;#id2&quot;/&gt;</div><div class="line"><a name="l04897"></a><span class="lineno"> 4897</span>&#160;            &lt;item href=&quot;#id3&quot;/&gt;</div><div class="line"><a name="l04898"></a><span class="lineno"> 4898</span>&#160;          &lt;/records&gt;</div><div class="line"><a name="l04899"></a><span class="lineno"> 4899</span>&#160;        &lt;/ns:DBupdate&gt;</div><div class="line"><a name="l04900"></a><span class="lineno"> 4900</span>&#160;        &lt;id id=&quot;id1&quot; xsi:type=&quot;ns:record&quot;&gt;</div><div class="line"><a name="l04901"></a><span class="lineno"> 4901</span>&#160;          &lt;name href=&quot;#id4&quot;/&gt;</div><div class="line"><a name="l04902"></a><span class="lineno"> 4902</span>&#160;          &lt;SSN&gt;1234567890&lt;/SSN&gt;</div><div class="line"><a name="l04903"></a><span class="lineno"> 4903</span>&#160;        &lt;/id&gt;</div><div class="line"><a name="l04904"></a><span class="lineno"> 4904</span>&#160;        &lt;id id=&quot;id2&quot; xsi:type=&quot;ns:record&quot;&gt;</div><div class="line"><a name="l04905"></a><span class="lineno"> 4905</span>&#160;          &lt;name href=&quot;#id5&quot;/&gt;</div><div class="line"><a name="l04906"></a><span class="lineno"> 4906</span>&#160;          &lt;SSN&gt;1987654320&lt;/SSN&gt;</div><div class="line"><a name="l04907"></a><span class="lineno"> 4907</span>&#160;        &lt;/id&gt;</div><div class="line"><a name="l04908"></a><span class="lineno"> 4908</span>&#160;        &lt;id id=&quot;id3&quot; xsi:type=&quot;ns:record&quot;&gt;</div><div class="line"><a name="l04909"></a><span class="lineno"> 4909</span>&#160;          &lt;name href=&quot;#id4&quot;/&gt;</div><div class="line"><a name="l04910"></a><span class="lineno"> 4910</span>&#160;          &lt;SSN&gt;2345678901&lt;/SSN&gt;</div><div class="line"><a name="l04911"></a><span class="lineno"> 4911</span>&#160;        &lt;/id&gt;</div><div class="line"><a name="l04912"></a><span class="lineno"> 4912</span>&#160;        &lt;id id=&quot;id4&quot; xsi:type=&quot;xsd:string&quot;&gt;Joe&lt;/id&gt;</div><div class="line"><a name="l04913"></a><span class="lineno"> 4913</span>&#160;        &lt;id id=&quot;id5&quot; xsi:type=&quot;xsd:string&quot;&gt;Jane&lt;/id&gt;</div><div class="line"><a name="l04914"></a><span class="lineno"> 4914</span>&#160;      &lt;/SOAP-ENV:Body&gt;</div><div class="line"><a name="l04915"></a><span class="lineno"> 4915</span>&#160;    &lt;/SOAP-ENV:Envelope&gt;</div><div class="line"><a name="l04916"></a><span class="lineno"> 4916</span>&#160;~~~</div><div class="line"><a name="l04917"></a><span class="lineno"> 4917</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l04918"></a><span class="lineno"> 4918</span>&#160;</div><div class="line"><a name="l04919"></a><span class="lineno"> 4919</span>&#160;SOAP 1.2 encoding is cleaner and produces more accurate XML encodings of data</div><div class="line"><a name="l04920"></a><span class="lineno"> 4920</span>&#160;graphs by setting the id attribute on the element that is referenced:</div><div class="line"><a name="l04921"></a><span class="lineno"> 4921</span>&#160;</div><div class="line"><a name="l04922"></a><span class="lineno"> 4922</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l04923"></a><span class="lineno"> 4923</span>&#160;~~~{.xml}</div><div class="line"><a name="l04924"></a><span class="lineno"> 4924</span>&#160;    &lt;SOAP-ENV:Envelope</div><div class="line"><a name="l04925"></a><span class="lineno"> 4925</span>&#160;      xmlns:SOAP-ENV=&quot;http://www.w3.org/2003/05/soap-envelope&quot;</div><div class="line"><a name="l04926"></a><span class="lineno"> 4926</span>&#160;      xmlns:SOAP-ENC=&quot;http://www.w3.org/2003/05/soap-encoding&quot;</div><div class="line"><a name="l04927"></a><span class="lineno"> 4927</span>&#160;      xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;</div><div class="line"><a name="l04928"></a><span class="lineno"> 4928</span>&#160;      xmlns:xsd=&quot;http://www.w3.org/2001/XMLSchema&quot;</div><div class="line"><a name="l04929"></a><span class="lineno"> 4929</span>&#160;      xmlsn:ns=&quot;urn:DB&quot;&gt;</div><div class="line"><a name="l04930"></a><span class="lineno"> 4930</span>&#160;      &lt;SOAP-ENV:Body&gt;</div><div class="line"><a name="l04931"></a><span class="lineno"> 4931</span>&#160;        &lt;ns:DBupdate SOAP-ENV:encodingStyle=&quot;http://www.w3.org/2003/05/soap-encoding&quot;&gt;</div><div class="line"><a name="l04932"></a><span class="lineno"> 4932</span>&#160;          &lt;records SOAP-ENC:itemType=&quot;ns:record&quot; SOAP-ENC:arraySize=&quot;3&quot;&gt;</div><div class="line"><a name="l04933"></a><span class="lineno"> 4933</span>&#160;            &lt;item&gt;</div><div class="line"><a name="l04934"></a><span class="lineno"> 4934</span>&#160;              &lt;name SOAP-ENC:id=&quot;_1&quot;&gt;Joe&lt;/name&gt;</div><div class="line"><a name="l04935"></a><span class="lineno"> 4935</span>&#160;              &lt;SSN&gt;1234567890&lt;/SSN&gt;</div><div class="line"><a name="l04936"></a><span class="lineno"> 4936</span>&#160;            &lt;/item&gt;</div><div class="line"><a name="l04937"></a><span class="lineno"> 4937</span>&#160;            &lt;item&gt;</div><div class="line"><a name="l04938"></a><span class="lineno"> 4938</span>&#160;              &lt;name&gt;Jane&lt;/name&gt;</div><div class="line"><a name="l04939"></a><span class="lineno"> 4939</span>&#160;              &lt;SSN&gt;1987654320&lt;/SSN&gt;</div><div class="line"><a name="l04940"></a><span class="lineno"> 4940</span>&#160;            &lt;/item&gt;</div><div class="line"><a name="l04941"></a><span class="lineno"> 4941</span>&#160;            &lt;item&gt;</div><div class="line"><a name="l04942"></a><span class="lineno"> 4942</span>&#160;              &lt;name SOAP-ENC:ref=&quot;_1&quot;/&gt;</div><div class="line"><a name="l04943"></a><span class="lineno"> 4943</span>&#160;              &lt;SSN&gt;2345678901&lt;/SSN&gt;</div><div class="line"><a name="l04944"></a><span class="lineno"> 4944</span>&#160;            &lt;/item&gt;</div><div class="line"><a name="l04945"></a><span class="lineno"> 4945</span>&#160;          &lt;/records&gt;</div><div class="line"><a name="l04946"></a><span class="lineno"> 4946</span>&#160;        &lt;/ns:DBupdate&gt;</div><div class="line"><a name="l04947"></a><span class="lineno"> 4947</span>&#160;      &lt;/SOAP-ENV:Body&gt;</div><div class="line"><a name="l04948"></a><span class="lineno"> 4948</span>&#160;    &lt;/SOAP-ENV:Envelope&gt;</div><div class="line"><a name="l04949"></a><span class="lineno"> 4949</span>&#160;~~~</div><div class="line"><a name="l04950"></a><span class="lineno"> 4950</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l04951"></a><span class="lineno"> 4951</span>&#160;</div><div class="line"><a name="l04952"></a><span class="lineno"> 4952</span>&#160;@note Some SOAP 1.2 applications consider the namespace `SOAP-ENC` of</div><div class="line"><a name="l04953"></a><span class="lineno"> 4953</span>&#160;&lt;i&gt;`SOAP-ENC:id`&lt;/i&gt; and &lt;i&gt;`SOAP-ENC:ref`&lt;/i&gt; optional.  With gSOAP, the SOAP</div><div class="line"><a name="l04954"></a><span class="lineno"> 4954</span>&#160;1.2 encoding serialization follows the 2007 standard, while accepting</div><div class="line"><a name="l04955"></a><span class="lineno"> 4955</span>&#160;unqualified id and ref attributes.</div><div class="line"><a name="l04956"></a><span class="lineno"> 4956</span>&#160;</div><div class="line"><a name="l04957"></a><span class="lineno"> 4957</span>&#160;To remove all rendered id-ref multi-referenced elements, use the</div><div class="line"><a name="l04958"></a><span class="lineno"> 4958</span>&#160;`SOAP_XML_TREE` flag to initialize the `soap` context.</div><div class="line"><a name="l04959"></a><span class="lineno"> 4959</span>&#160;</div><div class="line"><a name="l04960"></a><span class="lineno"> 4960</span>&#160;Some XSD validation rules are turned off with SOAP encoding, because of the</div><div class="line"><a name="l04961"></a><span class="lineno"> 4961</span>&#160;presence of additional attributes, such as id and ref/href, SOAP arrays with</div><div class="line"><a name="l04962"></a><span class="lineno"> 4962</span>&#160;arbitrary element tags for array elements, and the occurrence of additional</div><div class="line"><a name="l04963"></a><span class="lineno"> 4963</span>&#160;multi-ref elements in the SOAP 1.1 Body.</div><div class="line"><a name="l04964"></a><span class="lineno"> 4964</span>&#160;</div><div class="line"><a name="l04965"></a><span class="lineno"> 4965</span>&#160;The use of &quot;literal&quot; puts no restrictions on the XML in the SOAP Body.  Full</div><div class="line"><a name="l04966"></a><span class="lineno"> 4966</span>&#160;XSD validation is possible, which can be enabled with the `SOAP_XML_STRICT`</div><div class="line"><a name="l04967"></a><span class="lineno"> 4967</span>&#160;flag to initialize the `soap` context.  However, data graphs will be</div><div class="line"><a name="l04968"></a><span class="lineno"> 4968</span>&#160;serialized as trees and cycles in the data will be cut from the XML rendition.</div><div class="line"><a name="l04969"></a><span class="lineno"> 4969</span>&#160;</div><div class="line"><a name="l04970"></a><span class="lineno"> 4970</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l04971"></a><span class="lineno"> 4971</span>&#160;</div><div class="line"><a name="l04972"></a><span class="lineno"> 4972</span>&#160;SOAP 1.1 versus SOAP 1.2                                                 {#soap}</div><div class="line"><a name="l04973"></a><span class="lineno"> 4973</span>&#160;------------------------</div><div class="line"><a name="l04974"></a><span class="lineno"> 4974</span>&#160;</div><div class="line"><a name="l04975"></a><span class="lineno"> 4975</span>&#160;There are two SOAP protocol versions: 1.1 and 1.2. The gSOAP tools can switch</div><div class="line"><a name="l04976"></a><span class="lineno"> 4976</span>&#160;between the two versions seamlessly.  You can declare the default SOAP version</div><div class="line"><a name="l04977"></a><span class="lineno"> 4977</span>&#160;for a service operation as follows:</div><div class="line"><a name="l04978"></a><span class="lineno"> 4978</span>&#160;</div><div class="line"><a name="l04979"></a><span class="lineno"> 4979</span>&#160;~~~{.cpp}</div><div class="line"><a name="l04980"></a><span class="lineno"> 4980</span>&#160;    //gsoap ns service method-protocol: DBupdate SOAP1.2</div><div class="line"><a name="l04981"></a><span class="lineno"> 4981</span>&#160;~~~</div><div class="line"><a name="l04982"></a><span class="lineno"> 4982</span>&#160;</div><div class="line"><a name="l04983"></a><span class="lineno"> 4983</span>&#160;Use `SOAP` (SOAP 1.1), `SOAP1.1`, `SOAP1.2`, and `HTTP` to switch SOAP versions</div><div class="line"><a name="l04984"></a><span class="lineno"> 4984</span>&#160;or enable REST methods with HTTP POST.  See [service directives](#directives-1)</div><div class="line"><a name="l04985"></a><span class="lineno"> 4985</span>&#160;and [XML serialization](#non-soap).</div><div class="line"><a name="l04986"></a><span class="lineno"> 4986</span>&#160;</div><div class="line"><a name="l04987"></a><span class="lineno"> 4987</span>&#160;The soapcpp2 tool auto-generates client and server code.  At the client side,</div><div class="line"><a name="l04988"></a><span class="lineno"> 4988</span>&#160;this operation sends data with SOAP 1.2 but accepts responses also in SOAP 1.1.</div><div class="line"><a name="l04989"></a><span class="lineno"> 4989</span>&#160;At the server side, this operation accepts requests in SOAP 1.1 and 1.2 and</div><div class="line"><a name="l04990"></a><span class="lineno"> 4990</span>&#160;will return responses in the same SOAP version.</div><div class="line"><a name="l04991"></a><span class="lineno"> 4991</span>&#160;</div><div class="line"><a name="l04992"></a><span class="lineno"> 4992</span>&#160;As we discussed in the previous section, the SOAP 1.2 protocol has a cleaner</div><div class="line"><a name="l04993"></a><span class="lineno"> 4993</span>&#160;multi-referenced element serialization format that greatly enhances the</div><div class="line"><a name="l04994"></a><span class="lineno"> 4994</span>&#160;accuracy of data graph serialization with SOAP RPC encoding and is therefore</div><div class="line"><a name="l04995"></a><span class="lineno"> 4995</span>&#160;recommended.</div><div class="line"><a name="l04996"></a><span class="lineno"> 4996</span>&#160;</div><div class="line"><a name="l04997"></a><span class="lineno"> 4997</span>&#160;The SOAP 1.2 protocol default can also be set by importing and loading</div><div class="line"><a name="l04998"></a><span class="lineno"> 4998</span>&#160;&lt;i&gt;`gsoap/import/soap12.h`&lt;/i&gt;:</div><div class="line"><a name="l04999"></a><span class="lineno"> 4999</span>&#160;</div><div class="line"><a name="l05000"></a><span class="lineno"> 5000</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05001"></a><span class="lineno"> 5001</span>&#160;   #import &quot;soap12.h&quot;</div><div class="line"><a name="l05002"></a><span class="lineno"> 5002</span>&#160;~~~</div><div class="line"><a name="l05003"></a><span class="lineno"> 5003</span>&#160;</div><div class="line"><a name="l05004"></a><span class="lineno"> 5004</span>&#160;Finally, the soapcpp2 tool has options to force SOAP 1.1, SOAP 1.2, or remove</div><div class="line"><a name="l05005"></a><span class="lineno"> 5005</span>&#160;SOAP altogether with &lt;b&gt;`soapcpp2 -1`&lt;/b&gt; (SOAP 1.1), &lt;b&gt;`soapcpp2 -2`&lt;/b&gt;</div><div class="line"><a name="l05006"></a><span class="lineno"> 5006</span>&#160;(SOAP 1.2) and &lt;b&gt;`soapcpp2 -0`&lt;/b&gt; (plain XML, no SOAP).</div><div class="line"><a name="l05007"></a><span class="lineno"> 5007</span>&#160;</div><div class="line"><a name="l05008"></a><span class="lineno"> 5008</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l05009"></a><span class="lineno"> 5009</span>&#160;</div><div class="line"><a name="l05010"></a><span class="lineno"> 5010</span>&#160;XML serialization                                           {#non-soap}</div><div class="line"><a name="l05011"></a><span class="lineno"> 5011</span>&#160;-----------------</div><div class="line"><a name="l05012"></a><span class="lineno"> 5012</span>&#160;</div><div class="line"><a name="l05013"></a><span class="lineno"> 5013</span>&#160;You can serialize data to XML that is stored on the heap, on the stack (locals), and</div><div class="line"><a name="l05014"></a><span class="lineno"> 5014</span>&#160;static data as long as the serializable (i.e. non-transient) values are</div><div class="line"><a name="l05015"></a><span class="lineno"> 5015</span>&#160;properly initialized and pointers in the data structures are either NULL or</div><div class="line"><a name="l05016"></a><span class="lineno"> 5016</span>&#160;point to valid structures.</div><div class="line"><a name="l05017"></a><span class="lineno"> 5017</span>&#160;</div><div class="line"><a name="l05018"></a><span class="lineno"> 5018</span>&#160;When XML is deserialized into data, the data is put on the heap and managed by the</div><div class="line"><a name="l05019"></a><span class="lineno"> 5019</span>&#160;`::soap` context, see also [memory management](#memory).</div><div class="line"><a name="l05020"></a><span class="lineno"> 5020</span>&#160;</div><div class="line"><a name="l05021"></a><span class="lineno"> 5021</span>&#160;You can read and write XML directly to a file or stream with the serializing</div><div class="line"><a name="l05022"></a><span class="lineno"> 5022</span>&#160;[operations on classes and structs](#toxsd9-14).</div><div class="line"><a name="l05023"></a><span class="lineno"> 5023</span>&#160;</div><div class="line"><a name="l05024"></a><span class="lineno"> 5024</span>&#160;To define and use XML Web service client and service operations, we can declare</div><div class="line"><a name="l05025"></a><span class="lineno"> 5025</span>&#160;these operations in your interface header file with the data binding interface</div><div class="line"><a name="l05026"></a><span class="lineno"> 5026</span>&#160;for soapcpp2 as functions.  The function are translated by soapcpp2 to</div><div class="line"><a name="l05027"></a><span class="lineno"> 5027</span>&#160;client-side service invocation calls and server-side service operation</div><div class="line"><a name="l05028"></a><span class="lineno"> 5028</span>&#160;dispatchers.</div><div class="line"><a name="l05029"></a><span class="lineno"> 5029</span>&#160;</div><div class="line"><a name="l05030"></a><span class="lineno"> 5030</span>&#160;The REST operations POST, GET, and PUT are declared with `//gsoap` directives</div><div class="line"><a name="l05031"></a><span class="lineno"> 5031</span>&#160;in the interface header file for soapcpp2.  For example, a REST HTTP POST</div><div class="line"><a name="l05032"></a><span class="lineno"> 5032</span>&#160;operation is declared as follows:</div><div class="line"><a name="l05033"></a><span class="lineno"> 5033</span>&#160;</div><div class="line"><a name="l05034"></a><span class="lineno"> 5034</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05035"></a><span class="lineno"> 5035</span>&#160;    //gsoap ns service namespace:       urn:DB</div><div class="line"><a name="l05036"></a><span class="lineno"> 5036</span>&#160;    //gsoap ns service method-protocol: DBupdate POST</div><div class="line"><a name="l05037"></a><span class="lineno"> 5037</span>&#160;    int ns__DBupdate(...);</div><div class="line"><a name="l05038"></a><span class="lineno"> 5038</span>&#160;~~~</div><div class="line"><a name="l05039"></a><span class="lineno"> 5039</span>&#160;</div><div class="line"><a name="l05040"></a><span class="lineno"> 5040</span>&#160;There are no SOAP Envelope and SOAP Body elements in the payload for</div><div class="line"><a name="l05041"></a><span class="lineno"> 5041</span>&#160;`DBupdate`.  Also the XML serialization rules are identical to SOAP</div><div class="line"><a name="l05042"></a><span class="lineno"> 5042</span>&#160;document/literal, meaning no SOAP RPC encoding XML structures are implicitly</div><div class="line"><a name="l05043"></a><span class="lineno"> 5043</span>&#160;used.  The XML payload only has the operation name as an element with its</div><div class="line"><a name="l05044"></a><span class="lineno"> 5044</span>&#160;parameters serialized as subelements:</div><div class="line"><a name="l05045"></a><span class="lineno"> 5045</span>&#160;</div><div class="line"><a name="l05046"></a><span class="lineno"> 5046</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l05047"></a><span class="lineno"> 5047</span>&#160;~~~{.xml}</div><div class="line"><a name="l05048"></a><span class="lineno"> 5048</span>&#160;    &lt;ns:DBupdate xmln:ns=&quot;urn:DB&quot; ...&gt;</div><div class="line"><a name="l05049"></a><span class="lineno"> 5049</span>&#160;     ...</div><div class="line"><a name="l05050"></a><span class="lineno"> 5050</span>&#160;    &lt;/ns:DBupdate&gt;</div><div class="line"><a name="l05051"></a><span class="lineno"> 5051</span>&#160;~~~</div><div class="line"><a name="l05052"></a><span class="lineno"> 5052</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l05053"></a><span class="lineno"> 5053</span>&#160;</div><div class="line"><a name="l05054"></a><span class="lineno"> 5054</span>&#160;To force id-ref serialization with REST similar to SOAP 1.2 multi-reference</div><div class="line"><a name="l05055"></a><span class="lineno"> 5055</span>&#160;encoding, use the `SOAP_XML_GRAPH` flag to initialize the `soap` context.</div><div class="line"><a name="l05056"></a><span class="lineno"> 5056</span>&#160;The XML serialization includes id and ref attributes for multi-referenced</div><div class="line"><a name="l05057"></a><span class="lineno"> 5057</span>&#160;elements as follows:</div><div class="line"><a name="l05058"></a><span class="lineno"> 5058</span>&#160;</div><div class="line"><a name="l05059"></a><span class="lineno"> 5059</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l05060"></a><span class="lineno"> 5060</span>&#160;~~~{.xml}</div><div class="line"><a name="l05061"></a><span class="lineno"> 5061</span>&#160;    &lt;ns:DBupdate xmln:ns=&quot;urn:DB&quot; ...&gt;</div><div class="line"><a name="l05062"></a><span class="lineno"> 5062</span>&#160;      &lt;records&gt;</div><div class="line"><a name="l05063"></a><span class="lineno"> 5063</span>&#160;        &lt;item&gt;</div><div class="line"><a name="l05064"></a><span class="lineno"> 5064</span>&#160;          &lt;name id=&quot;_1&quot;&gt;Joe&lt;/name&gt;</div><div class="line"><a name="l05065"></a><span class="lineno"> 5065</span>&#160;          &lt;SSN&gt;1234567890&lt;/SSN&gt;</div><div class="line"><a name="l05066"></a><span class="lineno"> 5066</span>&#160;        &lt;/item&gt;</div><div class="line"><a name="l05067"></a><span class="lineno"> 5067</span>&#160;        &lt;item&gt;</div><div class="line"><a name="l05068"></a><span class="lineno"> 5068</span>&#160;          &lt;name&gt;Jane&lt;/name&gt;</div><div class="line"><a name="l05069"></a><span class="lineno"> 5069</span>&#160;          &lt;SSN&gt;1987654320&lt;/SSN&gt;</div><div class="line"><a name="l05070"></a><span class="lineno"> 5070</span>&#160;        &lt;/item&gt;</div><div class="line"><a name="l05071"></a><span class="lineno"> 5071</span>&#160;        &lt;item&gt;</div><div class="line"><a name="l05072"></a><span class="lineno"> 5072</span>&#160;          &lt;name ref=&quot;_1&quot;/&gt;</div><div class="line"><a name="l05073"></a><span class="lineno"> 5073</span>&#160;          &lt;SSN&gt;2345678901&lt;/SSN&gt;</div><div class="line"><a name="l05074"></a><span class="lineno"> 5074</span>&#160;        &lt;/item&gt;</div><div class="line"><a name="l05075"></a><span class="lineno"> 5075</span>&#160;      &lt;/records&gt;</div><div class="line"><a name="l05076"></a><span class="lineno"> 5076</span>&#160;    &lt;/ns:DBupdate&gt;</div><div class="line"><a name="l05077"></a><span class="lineno"> 5077</span>&#160;~~~</div><div class="line"><a name="l05078"></a><span class="lineno"> 5078</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l05079"></a><span class="lineno"> 5079</span>&#160;</div><div class="line"><a name="l05080"></a><span class="lineno"> 5080</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l05081"></a><span class="lineno"> 5081</span>&#160;</div><div class="line"><a name="l05082"></a><span class="lineno"> 5082</span>&#160;Input and output                                                           {#io}</div><div class="line"><a name="l05083"></a><span class="lineno"> 5083</span>&#160;================</div><div class="line"><a name="l05084"></a><span class="lineno"> 5084</span>&#160;</div><div class="line"><a name="l05085"></a><span class="lineno"> 5085</span>&#160;Reading and writing XML from/to files, streams and string buffers is done via</div><div class="line"><a name="l05086"></a><span class="lineno"> 5086</span>&#160;the managing `soap` context by setting one of the following context variables that</div><div class="line"><a name="l05087"></a><span class="lineno"> 5087</span>&#160;control IO sources and sinks:</div><div class="line"><a name="l05088"></a><span class="lineno"> 5088</span>&#160;</div><div class="line"><a name="l05089"></a><span class="lineno"> 5089</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05090"></a><span class="lineno"> 5090</span>&#160;    soap-&gt;recvfd = fd; // an int file descriptor to read from (0 by default)</div><div class="line"><a name="l05091"></a><span class="lineno"> 5091</span>&#160;    soap-&gt;sendfd = fd; // an int file descriptor to write to (1 by default)</div><div class="line"><a name="l05092"></a><span class="lineno"> 5092</span>&#160;    soap-&gt;is = &amp;is;    // C++ only: a std::istream is object to read from</div><div class="line"><a name="l05093"></a><span class="lineno"> 5093</span>&#160;    soap-&gt;os = &amp;os;    // C++ only: a std::ostream os object to write to</div><div class="line"><a name="l05094"></a><span class="lineno"> 5094</span>&#160;    soap-&gt;is = cs;     // C only: a const char* string to read from (soap-&gt;is will advance)</div><div class="line"><a name="l05095"></a><span class="lineno"> 5095</span>&#160;    soap-&gt;os = &amp;cs;    // C only: pointer to a const char*, will be set to point to the string output</div><div class="line"><a name="l05096"></a><span class="lineno"> 5096</span>&#160;~~~</div><div class="line"><a name="l05097"></a><span class="lineno"> 5097</span>&#160;</div><div class="line"><a name="l05098"></a><span class="lineno"> 5098</span>&#160;Normally, all of these context variables are NULL, which is required to send and</div><div class="line"><a name="l05099"></a><span class="lineno"> 5099</span>&#160;receive data over sockets by gSOAP client and server applications.  Therefore,</div><div class="line"><a name="l05100"></a><span class="lineno"> 5100</span>&#160;if you set any of these context variables in a client or server application</div><div class="line"><a name="l05101"></a><span class="lineno"> 5101</span>&#160;then you should reset them to NULL to ensure that socket communications are not</div><div class="line"><a name="l05102"></a><span class="lineno"> 5102</span>&#160;blocked.</div><div class="line"><a name="l05103"></a><span class="lineno"> 5103</span>&#160;</div><div class="line"><a name="l05104"></a><span class="lineno"> 5104</span>&#160;@note The use of `soap::is` and `soap::os` in C requires gSOAP 2.8.28 or greater.</div><div class="line"><a name="l05105"></a><span class="lineno"> 5105</span>&#160;</div><div class="line"><a name="l05106"></a><span class="lineno"> 5106</span>&#160;In the following sections, we present more details on how to read and write to</div><div class="line"><a name="l05107"></a><span class="lineno"> 5107</span>&#160;files and streams, and use string buffers as sources and sinks for XML data.</div><div class="line"><a name="l05108"></a><span class="lineno"> 5108</span>&#160;</div><div class="line"><a name="l05109"></a><span class="lineno"> 5109</span>&#160;In addition, you can set IO callback functions to handle IO at a lower level.</div><div class="line"><a name="l05110"></a><span class="lineno"> 5110</span>&#160;For more details on defining your own callback functions, see the</div><div class="line"><a name="l05111"></a><span class="lineno"> 5111</span>&#160;[gSOAP user guide.](../../guide/html/index.html)</div><div class="line"><a name="l05112"></a><span class="lineno"> 5112</span>&#160;</div><div class="line"><a name="l05113"></a><span class="lineno"> 5113</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l05114"></a><span class="lineno"> 5114</span>&#160;</div><div class="line"><a name="l05115"></a><span class="lineno"> 5115</span>&#160;Reading and writing from/to files and streams                             {#io1}</div><div class="line"><a name="l05116"></a><span class="lineno"> 5116</span>&#160;---------------------------------------------</div><div class="line"><a name="l05117"></a><span class="lineno"> 5117</span>&#160;</div><div class="line"><a name="l05118"></a><span class="lineno"> 5118</span>&#160;The default IO is standard input and output.  Other sources and sinks (those</div><div class="line"><a name="l05119"></a><span class="lineno"> 5119</span>&#160;listed above) will be used until you (re)set them.  For example with file-based</div><div class="line"><a name="l05120"></a><span class="lineno"> 5120</span>&#160;input and output:</div><div class="line"><a name="l05121"></a><span class="lineno"> 5121</span>&#160;</div><div class="line"><a name="l05122"></a><span class="lineno"> 5122</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05123"></a><span class="lineno"> 5123</span>&#160;    FILE *fp = fopen(&quot;record.xml&quot;, &quot;r&quot;);</div><div class="line"><a name="l05124"></a><span class="lineno"> 5124</span>&#160;    if (fp != NULL)</div><div class="line"><a name="l05125"></a><span class="lineno"> 5125</span>&#160;    {</div><div class="line"><a name="l05126"></a><span class="lineno"> 5126</span>&#160;      soap-&gt;recvfd = fileno(fp);    // get file descriptor of file to read from</div><div class="line"><a name="l05127"></a><span class="lineno"> 5127</span>&#160;      if (soap_read_ns__record(soap, &amp;pers1))</div><div class="line"><a name="l05128"></a><span class="lineno"> 5128</span>&#160;        ... // handle IO error</div><div class="line"><a name="l05129"></a><span class="lineno"> 5129</span>&#160;      fclose(fp);</div><div class="line"><a name="l05130"></a><span class="lineno"> 5130</span>&#160;      soap-&gt;recvfd = 0;             // read from stdin, or -1 to block reading</div><div class="line"><a name="l05131"></a><span class="lineno"> 5131</span>&#160;    }</div><div class="line"><a name="l05132"></a><span class="lineno"> 5132</span>&#160;</div><div class="line"><a name="l05133"></a><span class="lineno"> 5133</span>&#160;    FILE *fp = fopen(&quot;record.xml&quot;, &quot;w&quot;);</div><div class="line"><a name="l05134"></a><span class="lineno"> 5134</span>&#160;    if (fp != NULL)</div><div class="line"><a name="l05135"></a><span class="lineno"> 5135</span>&#160;    {</div><div class="line"><a name="l05136"></a><span class="lineno"> 5136</span>&#160;      soap-&gt;sendfd = fileno(fp);    // get file descriptor of file to write to</div><div class="line"><a name="l05137"></a><span class="lineno"> 5137</span>&#160;      if (soap_write_ns__record(soap, &amp;pers1))</div><div class="line"><a name="l05138"></a><span class="lineno"> 5138</span>&#160;        ... // handle IO error</div><div class="line"><a name="l05139"></a><span class="lineno"> 5139</span>&#160;      fclose(fp);</div><div class="line"><a name="l05140"></a><span class="lineno"> 5140</span>&#160;      soap-&gt;sendfd = 1;             // write to stdout, or -1 to block writing</div><div class="line"><a name="l05141"></a><span class="lineno"> 5141</span>&#160;    }</div><div class="line"><a name="l05142"></a><span class="lineno"> 5142</span>&#160;~~~</div><div class="line"><a name="l05143"></a><span class="lineno"> 5143</span>&#160;</div><div class="line"><a name="l05144"></a><span class="lineno"> 5144</span>&#160;Similar code with streams in C++:</div><div class="line"><a name="l05145"></a><span class="lineno"> 5145</span>&#160;</div><div class="line"><a name="l05146"></a><span class="lineno"> 5146</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05147"></a><span class="lineno"> 5147</span>&#160;    #include &lt;fstream&gt;</div><div class="line"><a name="l05148"></a><span class="lineno"> 5148</span>&#160;</div><div class="line"><a name="l05149"></a><span class="lineno"> 5149</span>&#160;    std::fstream fs;</div><div class="line"><a name="l05150"></a><span class="lineno"> 5150</span>&#160;    fs.open(&quot;record.xml&quot;, std::ios::in);</div><div class="line"><a name="l05151"></a><span class="lineno"> 5151</span>&#160;    if (fs)</div><div class="line"><a name="l05152"></a><span class="lineno"> 5152</span>&#160;    {</div><div class="line"><a name="l05153"></a><span class="lineno"> 5153</span>&#160;      soap-&gt;is = &amp;fs;</div><div class="line"><a name="l05154"></a><span class="lineno"> 5154</span>&#160;      if (soap_read__ns__record(soap, &amp;pers1))</div><div class="line"><a name="l05155"></a><span class="lineno"> 5155</span>&#160;        ... // handle IO error</div><div class="line"><a name="l05156"></a><span class="lineno"> 5156</span>&#160;      fs.close();</div><div class="line"><a name="l05157"></a><span class="lineno"> 5157</span>&#160;      soap-&gt;is = NULL;</div><div class="line"><a name="l05158"></a><span class="lineno"> 5158</span>&#160;    }</div><div class="line"><a name="l05159"></a><span class="lineno"> 5159</span>&#160;</div><div class="line"><a name="l05160"></a><span class="lineno"> 5160</span>&#160;    fs.open(&quot;record.xml&quot;, std::ios::out);</div><div class="line"><a name="l05161"></a><span class="lineno"> 5161</span>&#160;    if (fs)</div><div class="line"><a name="l05162"></a><span class="lineno"> 5162</span>&#160;    {</div><div class="line"><a name="l05163"></a><span class="lineno"> 5163</span>&#160;      soap-&gt;os = &amp;fs;</div><div class="line"><a name="l05164"></a><span class="lineno"> 5164</span>&#160;      if (soap_write__ns__record(soap, &amp;pers1))</div><div class="line"><a name="l05165"></a><span class="lineno"> 5165</span>&#160;        ... // handle IO error</div><div class="line"><a name="l05166"></a><span class="lineno"> 5166</span>&#160;      fs.close();</div><div class="line"><a name="l05167"></a><span class="lineno"> 5167</span>&#160;      soap-&gt;os = NULL;</div><div class="line"><a name="l05168"></a><span class="lineno"> 5168</span>&#160;    }</div><div class="line"><a name="l05169"></a><span class="lineno"> 5169</span>&#160;~~~</div><div class="line"><a name="l05170"></a><span class="lineno"> 5170</span>&#160;</div><div class="line"><a name="l05171"></a><span class="lineno"> 5171</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l05172"></a><span class="lineno"> 5172</span>&#160;</div><div class="line"><a name="l05173"></a><span class="lineno"> 5173</span>&#160;Reading and writing from/to string buffers                                {#io2}</div><div class="line"><a name="l05174"></a><span class="lineno"> 5174</span>&#160;------------------------------------------</div><div class="line"><a name="l05175"></a><span class="lineno"> 5175</span>&#160;</div><div class="line"><a name="l05176"></a><span class="lineno"> 5176</span>&#160;For C++ we recommend to use `std::stringstream` objects from the</div><div class="line"><a name="l05177"></a><span class="lineno"> 5177</span>&#160;&lt;i&gt;`sstream`&lt;/i&gt; C++ library as illustrated in the following example:</div><div class="line"><a name="l05178"></a><span class="lineno"> 5178</span>&#160;</div><div class="line"><a name="l05179"></a><span class="lineno"> 5179</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05180"></a><span class="lineno"> 5180</span>&#160;    #include &lt;sstream&gt;</div><div class="line"><a name="l05181"></a><span class="lineno"> 5181</span>&#160;</div><div class="line"><a name="l05182"></a><span class="lineno"> 5182</span>&#160;    std::stringstream ss;</div><div class="line"><a name="l05183"></a><span class="lineno"> 5183</span>&#160;    ss.str(&quot;...&quot;); // XML to parse</div><div class="line"><a name="l05184"></a><span class="lineno"> 5184</span>&#160;    soap-&gt;is = &amp;ss;</div><div class="line"><a name="l05185"></a><span class="lineno"> 5185</span>&#160;    if (soap_read__ns__record(soap, &amp;pers1))</div><div class="line"><a name="l05186"></a><span class="lineno"> 5186</span>&#160;      ... // handle IO error</div><div class="line"><a name="l05187"></a><span class="lineno"> 5187</span>&#160;    soap-&gt;is = NULL;</div><div class="line"><a name="l05188"></a><span class="lineno"> 5188</span>&#160;</div><div class="line"><a name="l05189"></a><span class="lineno"> 5189</span>&#160;    soap-&gt;os = &amp;ss;</div><div class="line"><a name="l05190"></a><span class="lineno"> 5190</span>&#160;    if (soap_write__ns__record(soap, &amp;pers1))</div><div class="line"><a name="l05191"></a><span class="lineno"> 5191</span>&#160;      ... // handle IO error</div><div class="line"><a name="l05192"></a><span class="lineno"> 5192</span>&#160;    soap-&gt;os = NULL;</div><div class="line"><a name="l05193"></a><span class="lineno"> 5193</span>&#160;    std::string s = ss.str(); // string with XML</div><div class="line"><a name="l05194"></a><span class="lineno"> 5194</span>&#160;~~~</div><div class="line"><a name="l05195"></a><span class="lineno"> 5195</span>&#160;</div><div class="line"><a name="l05196"></a><span class="lineno"> 5196</span>&#160;For C we can use `soap::is` and `soap::os` to point to strings of XML content</div><div class="line"><a name="l05197"></a><span class="lineno"> 5197</span>&#160;as follows (this requires gSOAP 2.8.28 or later):</div><div class="line"><a name="l05198"></a><span class="lineno"> 5198</span>&#160;</div><div class="line"><a name="l05199"></a><span class="lineno"> 5199</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05200"></a><span class="lineno"> 5200</span>&#160;    soap-&gt;is = &quot;...&quot;; // XML to parse</div><div class="line"><a name="l05201"></a><span class="lineno"> 5201</span>&#160;    if (soap_read__ns__record(soap, &amp;pers1))</div><div class="line"><a name="l05202"></a><span class="lineno"> 5202</span>&#160;      ... // handle IO error</div><div class="line"><a name="l05203"></a><span class="lineno"> 5203</span>&#160;    soap-&gt;is = NULL;</div><div class="line"><a name="l05204"></a><span class="lineno"> 5204</span>&#160;</div><div class="line"><a name="l05205"></a><span class="lineno"> 5205</span>&#160;    const char *cs = NULL;</div><div class="line"><a name="l05206"></a><span class="lineno"> 5206</span>&#160;    soap-&gt;os = &amp;cs;</div><div class="line"><a name="l05207"></a><span class="lineno"> 5207</span>&#160;    if (soap_write__ns__record(soap, &amp;pers1))</div><div class="line"><a name="l05208"></a><span class="lineno"> 5208</span>&#160;      ... // handle IO error</div><div class="line"><a name="l05209"></a><span class="lineno"> 5209</span>&#160;    soap-&gt;os = NULL;</div><div class="line"><a name="l05210"></a><span class="lineno"> 5210</span>&#160;    ... = cs; // string with XML (do not free(cs): managed by the context and freed with soap_end())</div><div class="line"><a name="l05211"></a><span class="lineno"> 5211</span>&#160;~~~</div><div class="line"><a name="l05212"></a><span class="lineno"> 5212</span>&#160;</div><div class="line"><a name="l05213"></a><span class="lineno"> 5213</span>&#160;The type of `soap::os` is a pointer to a `const char*` string.  The pointer is</div><div class="line"><a name="l05214"></a><span class="lineno"> 5214</span>&#160;set by the managing `soap` context to point to the XML data that is stored on</div><div class="line"><a name="l05215"></a><span class="lineno"> 5215</span>&#160;the context-managed heap.</div><div class="line"><a name="l05216"></a><span class="lineno"> 5216</span>&#160;</div><div class="line"><a name="l05217"></a><span class="lineno"> 5217</span>&#160;For earlier gSOAP versions we recommend to use IO callbacks `soap::frecv` and</div><div class="line"><a name="l05218"></a><span class="lineno"> 5218</span>&#160;`soap::fsend`, see the [gSOAP user guide.](../../guide/html/index.html).</div><div class="line"><a name="l05219"></a><span class="lineno"> 5219</span>&#160;</div><div class="line"><a name="l05220"></a><span class="lineno"> 5220</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l05221"></a><span class="lineno"> 5221</span>&#160;</div><div class="line"><a name="l05222"></a><span class="lineno"> 5222</span>&#160;Memory management                                                      {#memory}</div><div class="line"><a name="l05223"></a><span class="lineno"> 5223</span>&#160;=================</div><div class="line"><a name="l05224"></a><span class="lineno"> 5224</span>&#160;</div><div class="line"><a name="l05225"></a><span class="lineno"> 5225</span>&#160;Memory management with the `soap` context enables us to allocate data in</div><div class="line"><a name="l05226"></a><span class="lineno"> 5226</span>&#160;context-managed heap space that can be collectively deleted.  All deserialized</div><div class="line"><a name="l05227"></a><span class="lineno"> 5227</span>&#160;data is placed on the context-managed heap by the `soap` context of the engine.</div><div class="line"><a name="l05228"></a><span class="lineno"> 5228</span>&#160;</div><div class="line"><a name="l05229"></a><span class="lineno"> 5229</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l05230"></a><span class="lineno"> 5230</span>&#160;</div><div class="line"><a name="l05231"></a><span class="lineno"> 5231</span>&#160;Memory management in C                                                {#memory1}</div><div class="line"><a name="l05232"></a><span class="lineno"> 5232</span>&#160;----------------------</div><div class="line"><a name="l05233"></a><span class="lineno"> 5233</span>&#160;</div><div class="line"><a name="l05234"></a><span class="lineno"> 5234</span>&#160;When working with gSOAP in C (i.e. using &lt;b&gt;`wsdl2h -c`&lt;/b&gt; option &lt;b&gt;`-c`&lt;/b&gt;</div><div class="line"><a name="l05235"></a><span class="lineno"> 5235</span>&#160;or &lt;b&gt;`soapcpp2 -c`&lt;/b&gt; option &lt;b&gt;`-c`&lt;/b&gt;), data is allocated on the managed heap with:</div><div class="line"><a name="l05236"></a><span class="lineno"> 5236</span>&#160;</div><div class="line"><a name="l05237"></a><span class="lineno"> 5237</span>&#160;- `void *soap_malloc(struct soap*, size_t len)`.</div><div class="line"><a name="l05238"></a><span class="lineno"> 5238</span>&#160;</div><div class="line"><a name="l05239"></a><span class="lineno"> 5239</span>&#160;This function allocates `len` bytes on the heap managed by the specified</div><div class="line"><a name="l05240"></a><span class="lineno"> 5240</span>&#160;context and returns NULL when allocation failed.</div><div class="line"><a name="l05241"></a><span class="lineno"> 5241</span>&#160;</div><div class="line"><a name="l05242"></a><span class="lineno"> 5242</span>&#160;You can also make shallow copies of data with `soap_memdup` that uses</div><div class="line"><a name="l05243"></a><span class="lineno"> 5243</span>&#160;`soap_malloc` and a safe version of `memcpy` to copy a chunk of data `src` with</div><div class="line"><a name="l05244"></a><span class="lineno"> 5244</span>&#160;length `len` to the context-managed heap:</div><div class="line"><a name="l05245"></a><span class="lineno"> 5245</span>&#160;</div><div class="line"><a name="l05246"></a><span class="lineno"> 5246</span>&#160;- `void * soap_memdup(struct soap*, const void *src, size_t len)`</div><div class="line"><a name="l05247"></a><span class="lineno"> 5247</span>&#160;</div><div class="line"><a name="l05248"></a><span class="lineno"> 5248</span>&#160;This function returns a pointer to the copy.  This function requires gSOAP</div><div class="line"><a name="l05249"></a><span class="lineno"> 5249</span>&#160;2.8.27 or later.</div><div class="line"><a name="l05250"></a><span class="lineno"> 5250</span>&#160;</div><div class="line"><a name="l05251"></a><span class="lineno"> 5251</span>&#160;In gSOAP 2.8.35 and greater versions, you can use an auto-generated function to</div><div class="line"><a name="l05252"></a><span class="lineno"> 5252</span>&#160;allocate and initialize data of type `T` on the managed heap:</div><div class="line"><a name="l05253"></a><span class="lineno"> 5253</span>&#160;</div><div class="line"><a name="l05254"></a><span class="lineno"> 5254</span>&#160;- `T * soap_new_T(struct soap*, int n)`</div><div class="line"><a name="l05255"></a><span class="lineno"> 5255</span>&#160;</div><div class="line"><a name="l05256"></a><span class="lineno"> 5256</span>&#160;This function returns an array of length `n` of type `T` data that is default</div><div class="line"><a name="l05257"></a><span class="lineno"> 5257</span>&#160;initialized (by internally calling `soap_malloc(soap, n * sizeof(T))` and then</div><div class="line"><a name="l05258"></a><span class="lineno"> 5258</span>&#160;`soap_default_T(soap, T*)` on each array value).  Use a negative value or `n=1`</div><div class="line"><a name="l05259"></a><span class="lineno"> 5259</span>&#160;to allocate and initialize a single value.  This function returns NULL when</div><div class="line"><a name="l05260"></a><span class="lineno"> 5260</span>&#160;allocation failed.</div><div class="line"><a name="l05261"></a><span class="lineno"> 5261</span>&#160;</div><div class="line"><a name="l05262"></a><span class="lineno"> 5262</span>&#160;The `soap_malloc` function is essentially a wrapper around `malloc`, but</div><div class="line"><a name="l05263"></a><span class="lineno"> 5263</span>&#160;permits the `soap` context to track all heap allocations for collective</div><div class="line"><a name="l05264"></a><span class="lineno"> 5264</span>&#160;deletion with `soap_end(soap)`:</div><div class="line"><a name="l05265"></a><span class="lineno"> 5265</span>&#160;</div><div class="line"><a name="l05266"></a><span class="lineno"> 5266</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05267"></a><span class="lineno"> 5267</span>&#160;    #include &quot;soapH.h&quot;</div><div class="line"><a name="l05268"></a><span class="lineno"> 5268</span>&#160;    #include &quot;ns.nsmap&quot;</div><div class="line"><a name="l05269"></a><span class="lineno"> 5269</span>&#160;    ...</div><div class="line"><a name="l05270"></a><span class="lineno"> 5270</span>&#160;    struct soap *soap = soap_new(); // new context</div><div class="line"><a name="l05271"></a><span class="lineno"> 5271</span>&#160;    ...</div><div class="line"><a name="l05272"></a><span class="lineno"> 5272</span>&#160;    struct ns__record *record = (struct ns__record*)soap_malloc(soap, sizeof(struct ns__record));</div><div class="line"><a name="l05273"></a><span class="lineno"> 5273</span>&#160;    soap_default_ns__record(soap, record); // auto-generated struct initializer</div><div class="line"><a name="l05274"></a><span class="lineno"> 5274</span>&#160;    ...</div><div class="line"><a name="l05275"></a><span class="lineno"> 5275</span>&#160;    soap_destroy(soap); // only for C++, see section on C++ below</div><div class="line"><a name="l05276"></a><span class="lineno"> 5276</span>&#160;    soap_end(soap);     // delete record and all other heap allocations</div><div class="line"><a name="l05277"></a><span class="lineno"> 5277</span>&#160;    soap_free(soap);    // delete context</div><div class="line"><a name="l05278"></a><span class="lineno"> 5278</span>&#160;~~~</div><div class="line"><a name="l05279"></a><span class="lineno"> 5279</span>&#160;</div><div class="line"><a name="l05280"></a><span class="lineno"> 5280</span>&#160;All data on the managed heap is mass-deleted with `soap_end(soap)` which must</div><div class="line"><a name="l05281"></a><span class="lineno"> 5281</span>&#160;be called before `soap_done(soap)` or `soap_free(soap)`, which end the use of</div><div class="line"><a name="l05282"></a><span class="lineno"> 5282</span>&#160;the `soap` context and free the context, respectively.  Use</div><div class="line"><a name="l05283"></a><span class="lineno"> 5283</span>&#160;`soap_free(soap)` only when the context is allocated with `soap_new()`.  Use</div><div class="line"><a name="l05284"></a><span class="lineno"> 5284</span>&#160;`soap_done(soap)` only when the context is stack allocated (so cannot be</div><div class="line"><a name="l05285"></a><span class="lineno"> 5285</span>&#160;deleted from the heap).</div><div class="line"><a name="l05286"></a><span class="lineno"> 5286</span>&#160;</div><div class="line"><a name="l05287"></a><span class="lineno"> 5287</span>&#160;The managed heap is checked for memory leaks at run time when the source code</div><div class="line"><a name="l05288"></a><span class="lineno"> 5288</span>&#160;is compiled with option &lt;b&gt;`-DDEBUG`&lt;/b&gt;.</div><div class="line"><a name="l05289"></a><span class="lineno"> 5289</span>&#160;</div><div class="line"><a name="l05290"></a><span class="lineno"> 5290</span>&#160;The soapcpp2 auto-generated deserializers in C use `soap_malloc` to allocate</div><div class="line"><a name="l05291"></a><span class="lineno"> 5291</span>&#160;and populate deserialized structures, which are managed by the context for</div><div class="line"><a name="l05292"></a><span class="lineno"> 5292</span>&#160;collective deletion.</div><div class="line"><a name="l05293"></a><span class="lineno"> 5293</span>&#160;</div><div class="line"><a name="l05294"></a><span class="lineno"> 5294</span>&#160;To make `char*` and `wchar_t*` string copies to the context-managed heap, we</div><div class="line"><a name="l05295"></a><span class="lineno"> 5295</span>&#160;can use the functions:</div><div class="line"><a name="l05296"></a><span class="lineno"> 5296</span>&#160;</div><div class="line"><a name="l05297"></a><span class="lineno"> 5297</span>&#160;- `char *soap_strdup(struct soap*, const char *str)` and</div><div class="line"><a name="l05298"></a><span class="lineno"> 5298</span>&#160;</div><div class="line"><a name="l05299"></a><span class="lineno"> 5299</span>&#160;- `wchar_t *soap_wstrdup(struct soap*, const wchar_t *wstr)`.</div><div class="line"><a name="l05300"></a><span class="lineno"> 5300</span>&#160;</div><div class="line"><a name="l05301"></a><span class="lineno"> 5301</span>&#160;If your C compiler supports `typeof` then you can use the following macro to</div><div class="line"><a name="l05302"></a><span class="lineno"> 5302</span>&#160;simplify the managed heap allocation and initialization of primitive values:</div><div class="line"><a name="l05303"></a><span class="lineno"> 5303</span>&#160;</div><div class="line"><a name="l05304"></a><span class="lineno"> 5304</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05305"></a><span class="lineno"> 5305</span>&#160;    #define soap_assign(soap, lhs, rhs) (*(lhs = (typeof(lhs))soap_malloc(soap, sizeof(*lhs))) = rhs)</div><div class="line"><a name="l05306"></a><span class="lineno"> 5306</span>&#160;~~~</div><div class="line"><a name="l05307"></a><span class="lineno"> 5307</span>&#160;</div><div class="line"><a name="l05308"></a><span class="lineno"> 5308</span>&#160;Pointers to primitive values are often used for optional members.  For example,</div><div class="line"><a name="l05309"></a><span class="lineno"> 5309</span>&#160;assume we have the following struct:</div><div class="line"><a name="l05310"></a><span class="lineno"> 5310</span>&#160;</div><div class="line"><a name="l05311"></a><span class="lineno"> 5311</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05312"></a><span class="lineno"> 5312</span>&#160;    struct ns__record</div><div class="line"><a name="l05313"></a><span class="lineno"> 5313</span>&#160;    {</div><div class="line"><a name="l05314"></a><span class="lineno"> 5314</span>&#160;        const char        *name 1; // required (minOccurs=1)</div><div class="line"><a name="l05315"></a><span class="lineno"> 5315</span>&#160;        uint64_t          *SSN;    // optional (pointer means minOccurs=0)</div><div class="line"><a name="l05316"></a><span class="lineno"> 5316</span>&#160;        struct ns__record *spouse; // optional (pointer means minOccurs=0)</div><div class="line"><a name="l05317"></a><span class="lineno"> 5317</span>&#160;    };</div><div class="line"><a name="l05318"></a><span class="lineno"> 5318</span>&#160;~~~</div><div class="line"><a name="l05319"></a><span class="lineno"> 5319</span>&#160;</div><div class="line"><a name="l05320"></a><span class="lineno"> 5320</span>&#160;Use `soap_assign` to create a SSN value on the managed heap:</div><div class="line"><a name="l05321"></a><span class="lineno"> 5321</span>&#160;</div><div class="line"><a name="l05322"></a><span class="lineno"> 5322</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05323"></a><span class="lineno"> 5323</span>&#160;    struct soap *soap = soap_new(); // new context</div><div class="line"><a name="l05324"></a><span class="lineno"> 5324</span>&#160;    ...</div><div class="line"><a name="l05325"></a><span class="lineno"> 5325</span>&#160;    struct ns__record *record = (struct ns__record*)soap_malloc(soap, sizeof(struct ns__record));</div><div class="line"><a name="l05326"></a><span class="lineno"> 5326</span>&#160;    soap_default_ns__record(soap, record);</div><div class="line"><a name="l05327"></a><span class="lineno"> 5327</span>&#160;    record-&gt;name = soap_strdup(soap, &quot;Joe&quot;);</div><div class="line"><a name="l05328"></a><span class="lineno"> 5328</span>&#160;    soap_assign(soap, record-&gt;SSN, 1234567890UL);</div><div class="line"><a name="l05329"></a><span class="lineno"> 5329</span>&#160;    ...</div><div class="line"><a name="l05330"></a><span class="lineno"> 5330</span>&#160;    soap_end(soap);     // delete managed soap_malloc&#39;ed heap data</div><div class="line"><a name="l05331"></a><span class="lineno"> 5331</span>&#160;    soap_free(soap);    // delete context</div><div class="line"><a name="l05332"></a><span class="lineno"> 5332</span>&#160;~~~</div><div class="line"><a name="l05333"></a><span class="lineno"> 5333</span>&#160;</div><div class="line"><a name="l05334"></a><span class="lineno"> 5334</span>&#160;Without the `soap_assign` macro, you will need two lines of code, one to</div><div class="line"><a name="l05335"></a><span class="lineno"> 5335</span>&#160;allocate and one to assign (you should also use this if your system can run out</div><div class="line"><a name="l05336"></a><span class="lineno"> 5336</span>&#160;of memory):</div><div class="line"><a name="l05337"></a><span class="lineno"> 5337</span>&#160;</div><div class="line"><a name="l05338"></a><span class="lineno"> 5338</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05339"></a><span class="lineno"> 5339</span>&#160;    assert((record-&gt;SSN = (uint64_t*)soap_malloc(soap, sizeof(utint64_t))) != NULL);</div><div class="line"><a name="l05340"></a><span class="lineno"> 5340</span>&#160;    *record-&gt;SSN = 1234567890UL;</div><div class="line"><a name="l05341"></a><span class="lineno"> 5341</span>&#160;~~~</div><div class="line"><a name="l05342"></a><span class="lineno"> 5342</span>&#160;</div><div class="line"><a name="l05343"></a><span class="lineno"> 5343</span>&#160;The serializer can serialize any heap, stack, or static allocated data.  So we</div><div class="line"><a name="l05344"></a><span class="lineno"> 5344</span>&#160;can also create a new record as follows:</div><div class="line"><a name="l05345"></a><span class="lineno"> 5345</span>&#160;</div><div class="line"><a name="l05346"></a><span class="lineno"> 5346</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05347"></a><span class="lineno"> 5347</span>&#160;    struct soap *soap = soap_new(); // new context</div><div class="line"><a name="l05348"></a><span class="lineno"> 5348</span>&#160;    ...</div><div class="line"><a name="l05349"></a><span class="lineno"> 5349</span>&#160;    struct ns__record *record = (struct ns__record*)soap_malloc(soap, sizeof(struct ns__record));</div><div class="line"><a name="l05350"></a><span class="lineno"> 5350</span>&#160;    static uint64_t SSN = 1234567890UL;</div><div class="line"><a name="l05351"></a><span class="lineno"> 5351</span>&#160;    soap_default_ns__record(soap, record);</div><div class="line"><a name="l05352"></a><span class="lineno"> 5352</span>&#160;    record-&gt;name = &quot;Joe&quot;;</div><div class="line"><a name="l05353"></a><span class="lineno"> 5353</span>&#160;    record-&gt;SSN = &amp;SSN; // safe to use static values: the value of record-&gt;SSN is never changed</div><div class="line"><a name="l05354"></a><span class="lineno"> 5354</span>&#160;    ...</div><div class="line"><a name="l05355"></a><span class="lineno"> 5355</span>&#160;    soap_end(soap);     // delete managed soap_malloc&#39;ed heap data</div><div class="line"><a name="l05356"></a><span class="lineno"> 5356</span>&#160;    soap_free(soap);    // delete context</div><div class="line"><a name="l05357"></a><span class="lineno"> 5357</span>&#160;~~~</div><div class="line"><a name="l05358"></a><span class="lineno"> 5358</span>&#160;</div><div class="line"><a name="l05359"></a><span class="lineno"> 5359</span>&#160;Use the soapcpp2 auto-generated `soap_dup_T` functions to duplicate data into</div><div class="line"><a name="l05360"></a><span class="lineno"> 5360</span>&#160;another `soap` context (this requires &lt;b&gt;`soapcpp2 -Ec`&lt;/b&gt; option &lt;b&gt;`-Ec`&lt;/b&gt; to</div><div class="line"><a name="l05361"></a><span class="lineno"> 5361</span>&#160;generate), here shown for C with the second argument `dst` NULL because we want</div><div class="line"><a name="l05362"></a><span class="lineno"> 5362</span>&#160;to allocate a new managed structure:</div><div class="line"><a name="l05363"></a><span class="lineno"> 5363</span>&#160;</div><div class="line"><a name="l05364"></a><span class="lineno"> 5364</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05365"></a><span class="lineno"> 5365</span>&#160;    struct soap *other_soap = soap_new(); // another context</div><div class="line"><a name="l05366"></a><span class="lineno"> 5366</span>&#160;    struct ns__record *other_record = soap_dup_ns__record(other_soap, NULL, record);</div><div class="line"><a name="l05367"></a><span class="lineno"> 5367</span>&#160;    ...</div><div class="line"><a name="l05368"></a><span class="lineno"> 5368</span>&#160;    soap_destroy(other_soap); // only for C++, see section on C++ below</div><div class="line"><a name="l05369"></a><span class="lineno"> 5369</span>&#160;    soap_end(other_soap);     // delete other_record and all of its deep data</div><div class="line"><a name="l05370"></a><span class="lineno"> 5370</span>&#160;    soap_free(other_soap);    // delete context</div><div class="line"><a name="l05371"></a><span class="lineno"> 5371</span>&#160;~~~</div><div class="line"><a name="l05372"></a><span class="lineno"> 5372</span>&#160;</div><div class="line"><a name="l05373"></a><span class="lineno"> 5373</span>&#160;The only reason to use another `soap` context and not to use the primary `soap`</div><div class="line"><a name="l05374"></a><span class="lineno"> 5374</span>&#160;context is when the primary context must be destroyed together with all of the</div><div class="line"><a name="l05375"></a><span class="lineno"> 5375</span>&#160;objects it manages while some of the objects must be kept alive.  If the</div><div class="line"><a name="l05376"></a><span class="lineno"> 5376</span>&#160;objects that are kept alive contain deep cycles then this is the only option we</div><div class="line"><a name="l05377"></a><span class="lineno"> 5377</span>&#160;have, because deep copy with a managing `soap` context detects and preserves</div><div class="line"><a name="l05378"></a><span class="lineno"> 5378</span>&#160;these cycles unless the `SOAP_XML_TREE` flag is used with the `soap` context:</div><div class="line"><a name="l05379"></a><span class="lineno"> 5379</span>&#160;</div><div class="line"><a name="l05380"></a><span class="lineno"> 5380</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05381"></a><span class="lineno"> 5381</span>&#160;    struct soap *other_soap = soap_new1(SOAP_XML_TREE); // another context</div><div class="line"><a name="l05382"></a><span class="lineno"> 5382</span>&#160;    struct ns__record *other_record = soap_dup_ns__record(other_soap, NULL, record);</div><div class="line"><a name="l05383"></a><span class="lineno"> 5383</span>&#160;~~~</div><div class="line"><a name="l05384"></a><span class="lineno"> 5384</span>&#160;</div><div class="line"><a name="l05385"></a><span class="lineno"> 5385</span>&#160;The resulting deep copy will be a full copy of the source data structure as a</div><div class="line"><a name="l05386"></a><span class="lineno"> 5386</span>&#160;tree without co-referenced data (i.e. no digraph) and without cycles.  Cycles</div><div class="line"><a name="l05387"></a><span class="lineno"> 5387</span>&#160;are pruned and (one of the) pointers that forms a cycle is repaced by NULL.</div><div class="line"><a name="l05388"></a><span class="lineno"> 5388</span>&#160;</div><div class="line"><a name="l05389"></a><span class="lineno"> 5389</span>&#160;You can also deep copy into unmanaged space and use the auto-generated</div><div class="line"><a name="l05390"></a><span class="lineno"> 5390</span>&#160;`soap_del_T()` function (requires &lt;b&gt;`soapcpp2 -Ed`&lt;/b&gt; option &lt;b&gt;`-Ed`&lt;/b&gt; to generate) to delete</div><div class="line"><a name="l05391"></a><span class="lineno"> 5391</span>&#160;it later:</div><div class="line"><a name="l05392"></a><span class="lineno"> 5392</span>&#160;</div><div class="line"><a name="l05393"></a><span class="lineno"> 5393</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05394"></a><span class="lineno"> 5394</span>&#160;    struct ns__record *other_record = soap_dup_ns__record(NULL, NULL, record);</div><div class="line"><a name="l05395"></a><span class="lineno"> 5395</span>&#160;    ...</div><div class="line"><a name="l05396"></a><span class="lineno"> 5396</span>&#160;    soap_del_ns__record(other_record); // deep delete record data members</div><div class="line"><a name="l05397"></a><span class="lineno"> 5397</span>&#160;    free(other_record);                // delete the record</div><div class="line"><a name="l05398"></a><span class="lineno"> 5398</span>&#160;~~~</div><div class="line"><a name="l05399"></a><span class="lineno"> 5399</span>&#160;</div><div class="line"><a name="l05400"></a><span class="lineno"> 5400</span>&#160;But you should not do this for any data that has deep cycles in its runtime</div><div class="line"><a name="l05401"></a><span class="lineno"> 5401</span>&#160;data structure.  Cycles in the data structure will lead to non-termination when</div><div class="line"><a name="l05402"></a><span class="lineno"> 5402</span>&#160;making unmanaged deep copies.  Consider for example:</div><div class="line"><a name="l05403"></a><span class="lineno"> 5403</span>&#160;</div><div class="line"><a name="l05404"></a><span class="lineno"> 5404</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05405"></a><span class="lineno"> 5405</span>&#160;    struct ns__record</div><div class="line"><a name="l05406"></a><span class="lineno"> 5406</span>&#160;    {</div><div class="line"><a name="l05407"></a><span class="lineno"> 5407</span>&#160;        const char         *name 1; // required (minOccurs=1)</div><div class="line"><a name="l05408"></a><span class="lineno"> 5408</span>&#160;        uint64_t            SSN;    // required (non-pointer means minOccurs=1)</div><div class="line"><a name="l05409"></a><span class="lineno"> 5409</span>&#160;        struct ns__record  *spouse; // optional (pointer means minOccurs=0)</div><div class="line"><a name="l05410"></a><span class="lineno"> 5410</span>&#160;    };</div><div class="line"><a name="l05411"></a><span class="lineno"> 5411</span>&#160;~~~</div><div class="line"><a name="l05412"></a><span class="lineno"> 5412</span>&#160;</div><div class="line"><a name="l05413"></a><span class="lineno"> 5413</span>&#160;The code to populate a structure with a mutual spouse relationship:</div><div class="line"><a name="l05414"></a><span class="lineno"> 5414</span>&#160;</div><div class="line"><a name="l05415"></a><span class="lineno"> 5415</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05416"></a><span class="lineno"> 5416</span>&#160;    struct soap *soap = soap_new();</div><div class="line"><a name="l05417"></a><span class="lineno"> 5417</span>&#160;    ...</div><div class="line"><a name="l05418"></a><span class="lineno"> 5418</span>&#160;    struct ns__record pers1, pers2;</div><div class="line"><a name="l05419"></a><span class="lineno"> 5419</span>&#160;    soap_default_ns__record(soap, &amp;pers1);</div><div class="line"><a name="l05420"></a><span class="lineno"> 5420</span>&#160;    soap_default_ns__record(soap, &amp;pers2);</div><div class="line"><a name="l05421"></a><span class="lineno"> 5421</span>&#160;    pers1.name = &quot;Joe&quot;;                     // OK to serialize static data</div><div class="line"><a name="l05422"></a><span class="lineno"> 5422</span>&#160;    pers1.SSN = 1234567890;</div><div class="line"><a name="l05423"></a><span class="lineno"> 5423</span>&#160;    pers1.spouse = &amp;pers2;</div><div class="line"><a name="l05424"></a><span class="lineno"> 5424</span>&#160;    pers2.name = soap_strdup(soap, &quot;Jane&quot;); // allocates and copies a string</div><div class="line"><a name="l05425"></a><span class="lineno"> 5425</span>&#160;    pers2.SSN = 1987654320;</div><div class="line"><a name="l05426"></a><span class="lineno"> 5426</span>&#160;    pers2.spouse = &amp;pers1;</div><div class="line"><a name="l05427"></a><span class="lineno"> 5427</span>&#160;    ...</div><div class="line"><a name="l05428"></a><span class="lineno"> 5428</span>&#160;    struct ns__record *pers3 = soap_dup_ns__record(NULL, NULL, &amp;pers1); // BAD</div><div class="line"><a name="l05429"></a><span class="lineno"> 5429</span>&#160;    struct ns__record *pers4 = soap_dup_ns__record(soap, NULL, &amp;pers1); // OK</div><div class="line"><a name="l05430"></a><span class="lineno"> 5430</span>&#160;    soap_set_mode(soap, SOAP_XML_TREE);</div><div class="line"><a name="l05431"></a><span class="lineno"> 5431</span>&#160;    struct ns__record *pers5 = soap_dup_ns__record(soap, NULL, &amp;pers1); // OK</div><div class="line"><a name="l05432"></a><span class="lineno"> 5432</span>&#160;~~~</div><div class="line"><a name="l05433"></a><span class="lineno"> 5433</span>&#160;</div><div class="line"><a name="l05434"></a><span class="lineno"> 5434</span>&#160;The bad case is where there is no context used in the first argument.  The deep</div><div class="line"><a name="l05435"></a><span class="lineno"> 5435</span>&#160;copy functions use a context to keep track of co-referenced data nodes and</div><div class="line"><a name="l05436"></a><span class="lineno"> 5436</span>&#160;cycles in the data structure copies, to copy co-referenced nodes just once.</div><div class="line"><a name="l05437"></a><span class="lineno"> 5437</span>&#160;Co-references in a data structure are formed by pointers and smart pointers</div><div class="line"><a name="l05438"></a><span class="lineno"> 5438</span>&#160;such as `std::shared_ptr`, such that at least two pointers point to the same</div><div class="line"><a name="l05439"></a><span class="lineno"> 5439</span>&#160;data.</div><div class="line"><a name="l05440"></a><span class="lineno"> 5440</span>&#160;</div><div class="line"><a name="l05441"></a><span class="lineno"> 5441</span>&#160;The serializer can serialize any heap, stack, or static allocated data, such as</div><div class="line"><a name="l05442"></a><span class="lineno"> 5442</span>&#160;in the code shown above.  So we can serialize the stack-allocated `pers1`</div><div class="line"><a name="l05443"></a><span class="lineno"> 5443</span>&#160;record as follows:</div><div class="line"><a name="l05444"></a><span class="lineno"> 5444</span>&#160;</div><div class="line"><a name="l05445"></a><span class="lineno"> 5445</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05446"></a><span class="lineno"> 5446</span>&#160;    FILE *fp = fopen(&quot;record.xml&quot;, &quot;w&quot;);</div><div class="line"><a name="l05447"></a><span class="lineno"> 5447</span>&#160;    if (fp != NULL)</div><div class="line"><a name="l05448"></a><span class="lineno"> 5448</span>&#160;    {</div><div class="line"><a name="l05449"></a><span class="lineno"> 5449</span>&#160;      soap-&gt;sendfd = fileno(fp);           // file descriptor to write to</div><div class="line"><a name="l05450"></a><span class="lineno"> 5450</span>&#160;      soap_set_mode(soap, SOAP_XML_GRAPH); // support id-ref w/o requiring SOAP</div><div class="line"><a name="l05451"></a><span class="lineno"> 5451</span>&#160;      soap_clr_mode(soap, SOAP_XML_TREE);  // if set, clear</div><div class="line"><a name="l05452"></a><span class="lineno"> 5452</span>&#160;      soap_write_ns__record(soap, &amp;pers1);</div><div class="line"><a name="l05453"></a><span class="lineno"> 5453</span>&#160;      fclose(fp);</div><div class="line"><a name="l05454"></a><span class="lineno"> 5454</span>&#160;      soap-&gt;sendfd = -1;                   // block further writing</div><div class="line"><a name="l05455"></a><span class="lineno"> 5455</span>&#160;    }</div><div class="line"><a name="l05456"></a><span class="lineno"> 5456</span>&#160;~~~</div><div class="line"><a name="l05457"></a><span class="lineno"> 5457</span>&#160;</div><div class="line"><a name="l05458"></a><span class="lineno"> 5458</span>&#160;which produces an XML document record.xml that is similar to:</div><div class="line"><a name="l05459"></a><span class="lineno"> 5459</span>&#160;</div><div class="line"><a name="l05460"></a><span class="lineno"> 5460</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l05461"></a><span class="lineno"> 5461</span>&#160;~~~{.xml}</div><div class="line"><a name="l05462"></a><span class="lineno"> 5462</span>&#160;    &lt;ns:record xmlns:ns=&quot;urn:types&quot; id=&quot;Joe&quot;&gt;</div><div class="line"><a name="l05463"></a><span class="lineno"> 5463</span>&#160;      &lt;name&gt;Joe&lt;/name&gt;</div><div class="line"><a name="l05464"></a><span class="lineno"> 5464</span>&#160;      &lt;SSN&gt;1234567890&lt;/SSN&gt;</div><div class="line"><a name="l05465"></a><span class="lineno"> 5465</span>&#160;      &lt;spouse id=&quot;Jane&quot;&gt;</div><div class="line"><a name="l05466"></a><span class="lineno"> 5466</span>&#160;        &lt;name&gt;Jane&lt;/name&gt;</div><div class="line"><a name="l05467"></a><span class="lineno"> 5467</span>&#160;        &lt;SSN&gt;1987654320&lt;/SSN&gt;</div><div class="line"><a name="l05468"></a><span class="lineno"> 5468</span>&#160;        &lt;spouse ref=&quot;#Joe&quot;/&gt;</div><div class="line"><a name="l05469"></a><span class="lineno"> 5469</span>&#160;      &lt;/spouse&gt;</div><div class="line"><a name="l05470"></a><span class="lineno"> 5470</span>&#160;    &lt;/ns:record&gt;</div><div class="line"><a name="l05471"></a><span class="lineno"> 5471</span>&#160;~~~</div><div class="line"><a name="l05472"></a><span class="lineno"> 5472</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l05473"></a><span class="lineno"> 5473</span>&#160;</div><div class="line"><a name="l05474"></a><span class="lineno"> 5474</span>&#160;Deserialization of an XML document with a SOAP 1.1/1.2 encoded id-ref graph</div><div class="line"><a name="l05475"></a><span class="lineno"> 5475</span>&#160;leads to the same non-termination problem when we later try to copy the data</div><div class="line"><a name="l05476"></a><span class="lineno"> 5476</span>&#160;into unmanaged memory heap space:</div><div class="line"><a name="l05477"></a><span class="lineno"> 5477</span>&#160;    </div><div class="line"><a name="l05478"></a><span class="lineno"> 5478</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05479"></a><span class="lineno"> 5479</span>&#160;    struct soap *soap = soap_new1(SOAP_XML_GRAPH); // support id-ref w/o SOAP</div><div class="line"><a name="l05480"></a><span class="lineno"> 5480</span>&#160;    ...</div><div class="line"><a name="l05481"></a><span class="lineno"> 5481</span>&#160;    struct ns__record pers1;</div><div class="line"><a name="l05482"></a><span class="lineno"> 5482</span>&#160;    FILE *fp = fopen(&quot;record.xml&quot;, &quot;r&quot;);</div><div class="line"><a name="l05483"></a><span class="lineno"> 5483</span>&#160;    if (fp != NULL)</div><div class="line"><a name="l05484"></a><span class="lineno"> 5484</span>&#160;    {</div><div class="line"><a name="l05485"></a><span class="lineno"> 5485</span>&#160;      soap-&gt;recvfd = fileno(fp);</div><div class="line"><a name="l05486"></a><span class="lineno"> 5486</span>&#160;      if (soap_read_ns__record(soap, &amp;pers1))</div><div class="line"><a name="l05487"></a><span class="lineno"> 5487</span>&#160;        ... // handle IO error</div><div class="line"><a name="l05488"></a><span class="lineno"> 5488</span>&#160;      fclose(fp);</div><div class="line"><a name="l05489"></a><span class="lineno"> 5489</span>&#160;      soap-&gt;recvfd = -1;                    // blocks further reading</div><div class="line"><a name="l05490"></a><span class="lineno"> 5490</span>&#160;    }</div><div class="line"><a name="l05491"></a><span class="lineno"> 5491</span>&#160;    ...</div><div class="line"><a name="l05492"></a><span class="lineno"> 5492</span>&#160;    struct ns__record *pers3 = soap_dup_ns__record(NULL, NULL, &amp;pers1); // BAD</div><div class="line"><a name="l05493"></a><span class="lineno"> 5493</span>&#160;    struct ns__record *pers4 = soap_dup_ns__record(soap, NULL, &amp;pers1); // OK</div><div class="line"><a name="l05494"></a><span class="lineno"> 5494</span>&#160;    soap_set_mode(soap, SOAP_XML_TREE);</div><div class="line"><a name="l05495"></a><span class="lineno"> 5495</span>&#160;    struct ns__record *pers5 = soap_dup_ns__record(soap, NULL, &amp;pers1); // OK</div><div class="line"><a name="l05496"></a><span class="lineno"> 5496</span>&#160;~~~</div><div class="line"><a name="l05497"></a><span class="lineno"> 5497</span>&#160;</div><div class="line"><a name="l05498"></a><span class="lineno"> 5498</span>&#160;Copying data with `soap_dup_T(soap)` into managed heap memory space is always</div><div class="line"><a name="l05499"></a><span class="lineno"> 5499</span>&#160;safe.  Copying into unmanaged heap memory space requires diligence.  But</div><div class="line"><a name="l05500"></a><span class="lineno"> 5500</span>&#160;deleting unmanaged data is easy with `soap_del_T()`.</div><div class="line"><a name="l05501"></a><span class="lineno"> 5501</span>&#160;</div><div class="line"><a name="l05502"></a><span class="lineno"> 5502</span>&#160;You can also use `soap_del_T()` to delete structures that you created in C, but</div><div class="line"><a name="l05503"></a><span class="lineno"> 5503</span>&#160;only if these structures are created with `malloc` and do NOT contain pointers</div><div class="line"><a name="l05504"></a><span class="lineno"> 5504</span>&#160;to stack and static data.</div><div class="line"><a name="l05505"></a><span class="lineno"> 5505</span>&#160;</div><div class="line"><a name="l05506"></a><span class="lineno"> 5506</span>&#160;You can unlink one or more allocated objects from the managed heap to allow the</div><div class="line"><a name="l05507"></a><span class="lineno"> 5507</span>&#160;object to live after `soap_end(soap)` by using:</div><div class="line"><a name="l05508"></a><span class="lineno"> 5508</span>&#160;</div><div class="line"><a name="l05509"></a><span class="lineno"> 5509</span>&#160;- `void soap_unlink(struct soap *soap, void *ptr)`</div><div class="line"><a name="l05510"></a><span class="lineno"> 5510</span>&#160;</div><div class="line"><a name="l05511"></a><span class="lineno"> 5511</span>&#160;The unlinked heap-allocated data pointed to by `ptr` can be accessed after</div><div class="line"><a name="l05512"></a><span class="lineno"> 5512</span>&#160;`soap_end(soap)`.  Do not forget to free the data with `free(ptr)`.  Be aware</div><div class="line"><a name="l05513"></a><span class="lineno"> 5513</span>&#160;that `soap_unlink(soap, ptr)` does not perform a deep unlinkage.  If `ptr` is a</div><div class="line"><a name="l05514"></a><span class="lineno"> 5514</span>&#160;struct, pointer members will become invalid when pointing to objects on the</div><div class="line"><a name="l05515"></a><span class="lineno"> 5515</span>&#160;managed heap.  Use `soap_unlink(soap, ptr-&gt;member)` to unlink `member` as well.</div><div class="line"><a name="l05516"></a><span class="lineno"> 5516</span>&#160;</div><div class="line"><a name="l05517"></a><span class="lineno"> 5517</span>&#160;Finally, when data is allocated in managed memory heap space, either explicitly</div><div class="line"><a name="l05518"></a><span class="lineno"> 5518</span>&#160;with the allocation functions shown above or by the soapcpp2-generated</div><div class="line"><a name="l05519"></a><span class="lineno"> 5519</span>&#160;deserializers, you can delegate the management and deletion of this data to</div><div class="line"><a name="l05520"></a><span class="lineno"> 5520</span>&#160;another `soap` context.  That context will be responsible to delete the data</div><div class="line"><a name="l05521"></a><span class="lineno"> 5521</span>&#160;with `soap_end(soap)` later:</div><div class="line"><a name="l05522"></a><span class="lineno"> 5522</span>&#160;</div><div class="line"><a name="l05523"></a><span class="lineno"> 5523</span>&#160;- `void delegate_deletion(struct soap *soap_from, struct soap *soap_to)`</div><div class="line"><a name="l05524"></a><span class="lineno"> 5524</span>&#160;</div><div class="line"><a name="l05525"></a><span class="lineno"> 5525</span>&#160;This allows the `soap_from` context to be deleted with `soap_free(soap_from)`</div><div class="line"><a name="l05526"></a><span class="lineno"> 5526</span>&#160;(assuming it is allocated with `soap_new()`, use `soap_done(soap_from)` when</div><div class="line"><a name="l05527"></a><span class="lineno"> 5527</span>&#160;`soap_from` is stack-allocated) while the managed data remains intact.  You</div><div class="line"><a name="l05528"></a><span class="lineno"> 5528</span>&#160;can use this function any time, to delegate management and deletion to another</div><div class="line"><a name="l05529"></a><span class="lineno"> 5529</span>&#160;context `soap_to` and then continue with the current context.  You can also use</div><div class="line"><a name="l05530"></a><span class="lineno"> 5530</span>&#160;different source `soap_from` contexts to delegate management and deletion to</div><div class="line"><a name="l05531"></a><span class="lineno"> 5531</span>&#160;the other `soap_to` context.  To mass delete all managed data, use</div><div class="line"><a name="l05532"></a><span class="lineno"> 5532</span>&#160;`soap_end(soap_to)`.</div><div class="line"><a name="l05533"></a><span class="lineno"> 5533</span>&#160;</div><div class="line"><a name="l05534"></a><span class="lineno"> 5534</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l05535"></a><span class="lineno"> 5535</span>&#160;</div><div class="line"><a name="l05536"></a><span class="lineno"> 5536</span>&#160;Memory management in C++                                              {#memory2}</div><div class="line"><a name="l05537"></a><span class="lineno"> 5537</span>&#160;------------------------</div><div class="line"><a name="l05538"></a><span class="lineno"> 5538</span>&#160;</div><div class="line"><a name="l05539"></a><span class="lineno"> 5539</span>&#160;When working with gSOAP in C++, the engine allocates data on a managed heap</div><div class="line"><a name="l05540"></a><span class="lineno"> 5540</span>&#160;using `soap_new_T(soap)` to allocate a type with type name `T`.  Managed heap</div><div class="line"><a name="l05541"></a><span class="lineno"> 5541</span>&#160;allocation is tracked by the `soap` context for collective deletion with</div><div class="line"><a name="l05542"></a><span class="lineno"> 5542</span>&#160;`soap_destroy(soap)` for structs, classes, and templates and with</div><div class="line"><a name="l05543"></a><span class="lineno"> 5543</span>&#160;`soap_end(soap)` for everything else.</div><div class="line"><a name="l05544"></a><span class="lineno"> 5544</span>&#160;</div><div class="line"><a name="l05545"></a><span class="lineno"> 5545</span>&#160;You should only use `soap_malloc(struct soap*, size_t len)` to allocate</div><div class="line"><a name="l05546"></a><span class="lineno"> 5546</span>&#160;primitive types because constructors are not invoked.  Therefore, `soap_new_T`</div><div class="line"><a name="l05547"></a><span class="lineno"> 5547</span>&#160;is preferred.  The auto-generated `T * soap_new_T(struct soap*)` returns data</div><div class="line"><a name="l05548"></a><span class="lineno"> 5548</span>&#160;allocated on the managed heap for type `T`.  The data is mass-deleted with</div><div class="line"><a name="l05549"></a><span class="lineno"> 5549</span>&#160;`soap_destroy(soap)` followed by `soap_end(soap)`.</div><div class="line"><a name="l05550"></a><span class="lineno"> 5550</span>&#160;</div><div class="line"><a name="l05551"></a><span class="lineno"> 5551</span>&#160;The `soap_new_T` functions return NULL when allocation fails.  C++ exceptions</div><div class="line"><a name="l05552"></a><span class="lineno"> 5552</span>&#160;are never raised by the engine and serializers when data is allocated.</div><div class="line"><a name="l05553"></a><span class="lineno"> 5553</span>&#160;</div><div class="line"><a name="l05554"></a><span class="lineno"> 5554</span>&#160;There are four variations of `soap_new_T` functions to allocate data of type</div><div class="line"><a name="l05555"></a><span class="lineno"> 5555</span>&#160;`T` that soapcpp2 auto-generates:</div><div class="line"><a name="l05556"></a><span class="lineno"> 5556</span>&#160;</div><div class="line"><a name="l05557"></a><span class="lineno"> 5557</span>&#160;- `T * soap_new_T(struct soap*)` returns a new instance of `T` that is default</div><div class="line"><a name="l05558"></a><span class="lineno"> 5558</span>&#160;  initialized.  For classes, initialization is internally performed using the</div><div class="line"><a name="l05559"></a><span class="lineno"> 5559</span>&#160;  soapcpp2 auto-generated `void T::soap_default(struct soap*)` method of the</div><div class="line"><a name="l05560"></a><span class="lineno"> 5560</span>&#160;  class, but ONLY IF the soapcpp2 auto-generated default constructor is used</div><div class="line"><a name="l05561"></a><span class="lineno"> 5561</span>&#160;  that invokes `soap_default()` and was not replaced by a user-defined default</div><div class="line"><a name="l05562"></a><span class="lineno"> 5562</span>&#160;  constructor.</div><div class="line"><a name="l05563"></a><span class="lineno"> 5563</span>&#160;</div><div class="line"><a name="l05564"></a><span class="lineno"> 5564</span>&#160;- `T * soap_new_T(struct soap*, int n)` returns an array of `n` new instances of</div><div class="line"><a name="l05565"></a><span class="lineno"> 5565</span>&#160;  `T`.  The instances in the array are default initialized as described above.</div><div class="line"><a name="l05566"></a><span class="lineno"> 5566</span>&#160;</div><div class="line"><a name="l05567"></a><span class="lineno"> 5567</span>&#160;- `T * soap_new_req_T(struct soap*, ...)` (structs and classes only) returns a</div><div class="line"><a name="l05568"></a><span class="lineno"> 5568</span>&#160;  new instance of `T` and sets the required data members to the values</div><div class="line"><a name="l05569"></a><span class="lineno"> 5569</span>&#160;  specified in `...`.  The required data members are those with nonzero</div><div class="line"><a name="l05570"></a><span class="lineno"> 5570</span>&#160;  minOccurs, see the subsections on</div><div class="line"><a name="l05571"></a><span class="lineno"> 5571</span>&#160;  [(smart) pointer members and their occurrence constraints](#toxsd9-8) and</div><div class="line"><a name="l05572"></a><span class="lineno"> 5572</span>&#160;  [container and array members and their occurrence constraints](#toxsd9-9).</div><div class="line"><a name="l05573"></a><span class="lineno"> 5573</span>&#160;</div><div class="line"><a name="l05574"></a><span class="lineno"> 5574</span>&#160;- `T * soap_new_set_T(struct soap*, ...)` (structs and classes only) returns a</div><div class="line"><a name="l05575"></a><span class="lineno"> 5575</span>&#160;  new instance of `T` and sets the public/serializable data members to the values</div><div class="line"><a name="l05576"></a><span class="lineno"> 5576</span>&#160;  specified in `...`.</div><div class="line"><a name="l05577"></a><span class="lineno"> 5577</span>&#160;</div><div class="line"><a name="l05578"></a><span class="lineno"> 5578</span>&#160;The above functions can be invoked with a NULL `soap` context, but you are then</div><div class="line"><a name="l05579"></a><span class="lineno"> 5579</span>&#160;responsible to use `delete T` to remove this instance from the unmanaged heap.</div><div class="line"><a name="l05580"></a><span class="lineno"> 5580</span>&#160;</div><div class="line"><a name="l05581"></a><span class="lineno"> 5581</span>&#160;For example, to allocate a managed `std::string` you can use:</div><div class="line"><a name="l05582"></a><span class="lineno"> 5582</span>&#160;</div><div class="line"><a name="l05583"></a><span class="lineno"> 5583</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05584"></a><span class="lineno"> 5584</span>&#160;    std::string *s = soap_new_std__string(soap);</div><div class="line"><a name="l05585"></a><span class="lineno"> 5585</span>&#160;~~~</div><div class="line"><a name="l05586"></a><span class="lineno"> 5586</span>&#160;</div><div class="line"><a name="l05587"></a><span class="lineno"> 5587</span>&#160;To throw a `std::bad_alloc` exception when memory allocation fails, we can define the</div><div class="line"><a name="l05588"></a><span class="lineno"> 5588</span>&#160;following class and macro:</div><div class="line"><a name="l05589"></a><span class="lineno"> 5589</span>&#160;</div><div class="line"><a name="l05590"></a><span class="lineno"> 5590</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05591"></a><span class="lineno"> 5591</span>&#160;    class alloc_check {</div><div class="line"><a name="l05592"></a><span class="lineno"> 5592</span>&#160;     public:</div><div class="line"><a name="l05593"></a><span class="lineno"> 5593</span>&#160;      template&lt;typename T&gt;</div><div class="line"><a name="l05594"></a><span class="lineno"> 5594</span>&#160;      T operator=(T ptr)</div><div class="line"><a name="l05595"></a><span class="lineno"> 5595</span>&#160;      {</div><div class="line"><a name="l05596"></a><span class="lineno"> 5596</span>&#160;        if (ptr == NULL)</div><div class="line"><a name="l05597"></a><span class="lineno"> 5597</span>&#160;          throw std::bad_alloc();</div><div class="line"><a name="l05598"></a><span class="lineno"> 5598</span>&#160;        return ptr;</div><div class="line"><a name="l05599"></a><span class="lineno"> 5599</span>&#160;      }</div><div class="line"><a name="l05600"></a><span class="lineno"> 5600</span>&#160;    };</div><div class="line"><a name="l05601"></a><span class="lineno"> 5601</span>&#160;</div><div class="line"><a name="l05602"></a><span class="lineno"> 5602</span>&#160;    #define CHECK alloc_check() =</div><div class="line"><a name="l05603"></a><span class="lineno"> 5603</span>&#160;~~~</div><div class="line"><a name="l05604"></a><span class="lineno"> 5604</span>&#160;</div><div class="line"><a name="l05605"></a><span class="lineno"> 5605</span>&#160;And use `CHECK` as follows to throw an exception when memory allocation fails:</div><div class="line"><a name="l05606"></a><span class="lineno"> 5606</span>&#160;</div><div class="line"><a name="l05607"></a><span class="lineno"> 5607</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05608"></a><span class="lineno"> 5608</span>&#160;    std::string *s = CHECK soap_new_std__string(soap);</div><div class="line"><a name="l05609"></a><span class="lineno"> 5609</span>&#160;~~~</div><div class="line"><a name="l05610"></a><span class="lineno"> 5610</span>&#160;</div><div class="line"><a name="l05611"></a><span class="lineno"> 5611</span>&#160;To throw a `std::runtime_exception` when memory allocation fails, with file</div><div class="line"><a name="l05612"></a><span class="lineno"> 5612</span>&#160;and line number information where the error occurred, we can define the</div><div class="line"><a name="l05613"></a><span class="lineno"> 5613</span>&#160;following revised version of our exception-throwing macro:</div><div class="line"><a name="l05614"></a><span class="lineno"> 5614</span>&#160;</div><div class="line"><a name="l05615"></a><span class="lineno"> 5615</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05616"></a><span class="lineno"> 5616</span>&#160;    class alloc_failure : public std::runtime_error {</div><div class="line"><a name="l05617"></a><span class="lineno"> 5617</span>&#160;     public:</div><div class="line"><a name="l05618"></a><span class="lineno"> 5618</span>&#160;      alloc_failure(const char *file, size_t line) : std::runtime_error(error(file, line))</div><div class="line"><a name="l05619"></a><span class="lineno"> 5619</span>&#160;      { }</div><div class="line"><a name="l05620"></a><span class="lineno"> 5620</span>&#160;     private:</div><div class="line"><a name="l05621"></a><span class="lineno"> 5621</span>&#160;      std::string error(const char *file, size_t line) const</div><div class="line"><a name="l05622"></a><span class="lineno"> 5622</span>&#160;      {</div><div class="line"><a name="l05623"></a><span class="lineno"> 5623</span>&#160;        std::stringstream ss;</div><div class="line"><a name="l05624"></a><span class="lineno"> 5624</span>&#160;        ss &lt;&lt; &quot;Memory allocation failed in &quot; &lt;&lt; file &lt;&lt; &quot; at line &quot; &lt;&lt; line;</div><div class="line"><a name="l05625"></a><span class="lineno"> 5625</span>&#160;        return ss.str();</div><div class="line"><a name="l05626"></a><span class="lineno"> 5626</span>&#160;      }</div><div class="line"><a name="l05627"></a><span class="lineno"> 5627</span>&#160;    };</div><div class="line"><a name="l05628"></a><span class="lineno"> 5628</span>&#160;</div><div class="line"><a name="l05629"></a><span class="lineno"> 5629</span>&#160;    class alloc_check_with_info {</div><div class="line"><a name="l05630"></a><span class="lineno"> 5630</span>&#160;     public:</div><div class="line"><a name="l05631"></a><span class="lineno"> 5631</span>&#160;      alloc_check_with_info(const char *file, size_t line) : file(file), line(line)</div><div class="line"><a name="l05632"></a><span class="lineno"> 5632</span>&#160;      { }</div><div class="line"><a name="l05633"></a><span class="lineno"> 5633</span>&#160;      template&lt;typename T&gt;</div><div class="line"><a name="l05634"></a><span class="lineno"> 5634</span>&#160;      T operator=(T ptr) const</div><div class="line"><a name="l05635"></a><span class="lineno"> 5635</span>&#160;      {</div><div class="line"><a name="l05636"></a><span class="lineno"> 5636</span>&#160;        if (ptr == NULL)</div><div class="line"><a name="l05637"></a><span class="lineno"> 5637</span>&#160;          throw alloc_failure(file, line);</div><div class="line"><a name="l05638"></a><span class="lineno"> 5638</span>&#160;        return ptr;</div><div class="line"><a name="l05639"></a><span class="lineno"> 5639</span>&#160;      }</div><div class="line"><a name="l05640"></a><span class="lineno"> 5640</span>&#160;      const char *file;</div><div class="line"><a name="l05641"></a><span class="lineno"> 5641</span>&#160;      size_t line;</div><div class="line"><a name="l05642"></a><span class="lineno"> 5642</span>&#160;    };</div><div class="line"><a name="l05643"></a><span class="lineno"> 5643</span>&#160;</div><div class="line"><a name="l05644"></a><span class="lineno"> 5644</span>&#160;    #define CHECK alloc_check_with_info(__FILE__, __LINE__) =</div><div class="line"><a name="l05645"></a><span class="lineno"> 5645</span>&#160;~~~</div><div class="line"><a name="l05646"></a><span class="lineno"> 5646</span>&#160;</div><div class="line"><a name="l05647"></a><span class="lineno"> 5647</span>&#160;And use `CHECK` as follows to throw an exception with the file and line number</div><div class="line"><a name="l05648"></a><span class="lineno"> 5648</span>&#160;of the location where memory allocation failed:</div><div class="line"><a name="l05649"></a><span class="lineno"> 5649</span>&#160;</div><div class="line"><a name="l05650"></a><span class="lineno"> 5650</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05651"></a><span class="lineno"> 5651</span>&#160;    std::string *s = CHECK soap_new_std__string(soap);</div><div class="line"><a name="l05652"></a><span class="lineno"> 5652</span>&#160;~~~</div><div class="line"><a name="l05653"></a><span class="lineno"> 5653</span>&#160;</div><div class="line"><a name="l05654"></a><span class="lineno"> 5654</span>&#160;Primitive types and arrays of primitive values may be allocated with</div><div class="line"><a name="l05655"></a><span class="lineno"> 5655</span>&#160;`soap_malloc` (actually, `soap_new_T` calls `soap_malloc` for primitive type</div><div class="line"><a name="l05656"></a><span class="lineno"> 5656</span>&#160;`T`).  All primitive types (i.e. no classes, structs, class templates,</div><div class="line"><a name="l05657"></a><span class="lineno"> 5657</span>&#160;containers, and smart pointers) are allocated with `soap_malloc` for reasons of</div><div class="line"><a name="l05658"></a><span class="lineno"> 5658</span>&#160;efficiency.</div><div class="line"><a name="l05659"></a><span class="lineno"> 5659</span>&#160;</div><div class="line"><a name="l05660"></a><span class="lineno"> 5660</span>&#160;You can use a C++ template to simplify the managed allocation and initialization</div><div class="line"><a name="l05661"></a><span class="lineno"> 5661</span>&#160;of primitive values as follows (this is for primitive types only):</div><div class="line"><a name="l05662"></a><span class="lineno"> 5662</span>&#160;</div><div class="line"><a name="l05663"></a><span class="lineno"> 5663</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05664"></a><span class="lineno"> 5664</span>&#160;    template&lt;class T&gt;</div><div class="line"><a name="l05665"></a><span class="lineno"> 5665</span>&#160;    T * soap_make(struct soap *soap, T val)</div><div class="line"><a name="l05666"></a><span class="lineno"> 5666</span>&#160;    {</div><div class="line"><a name="l05667"></a><span class="lineno"> 5667</span>&#160;      T *p = (T*)soap_malloc(soap, sizeof(T));</div><div class="line"><a name="l05668"></a><span class="lineno"> 5668</span>&#160;      if (p == NULL)</div><div class="line"><a name="l05669"></a><span class="lineno"> 5669</span>&#160;        throw std::bad_alloc();</div><div class="line"><a name="l05670"></a><span class="lineno"> 5670</span>&#160;      *p = val;</div><div class="line"><a name="l05671"></a><span class="lineno"> 5671</span>&#160;      return p;</div><div class="line"><a name="l05672"></a><span class="lineno"> 5672</span>&#160;    }</div><div class="line"><a name="l05673"></a><span class="lineno"> 5673</span>&#160;~~~</div><div class="line"><a name="l05674"></a><span class="lineno"> 5674</span>&#160;</div><div class="line"><a name="l05675"></a><span class="lineno"> 5675</span>&#160;For example, assuming we have the following class:</div><div class="line"><a name="l05676"></a><span class="lineno"> 5676</span>&#160;</div><div class="line"><a name="l05677"></a><span class="lineno"> 5677</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05678"></a><span class="lineno"> 5678</span>&#160;    class ns__record</div><div class="line"><a name="l05679"></a><span class="lineno"> 5679</span>&#160;    {</div><div class="line"><a name="l05680"></a><span class="lineno"> 5680</span>&#160;     public:</div><div class="line"><a name="l05681"></a><span class="lineno"> 5681</span>&#160;        std::string  name;   // required (non-pointer means minOccurs=1)</div><div class="line"><a name="l05682"></a><span class="lineno"> 5682</span>&#160;        uint64_t    *SSN;    // optional (pointer means minOccurs=0)</div><div class="line"><a name="l05683"></a><span class="lineno"> 5683</span>&#160;        ns__record  *spouse; // optional (pointer means minOccurs=0)</div><div class="line"><a name="l05684"></a><span class="lineno"> 5684</span>&#160;    };</div><div class="line"><a name="l05685"></a><span class="lineno"> 5685</span>&#160;~~~</div><div class="line"><a name="l05686"></a><span class="lineno"> 5686</span>&#160;</div><div class="line"><a name="l05687"></a><span class="lineno"> 5687</span>&#160;You can instantiate a record by using the auto-generated</div><div class="line"><a name="l05688"></a><span class="lineno"> 5688</span>&#160;`soap_new_set_ns__record` and use `soap_make` to create a SSN value on the</div><div class="line"><a name="l05689"></a><span class="lineno"> 5689</span>&#160;managed heap as follows:</div><div class="line"><a name="l05690"></a><span class="lineno"> 5690</span>&#160;</div><div class="line"><a name="l05691"></a><span class="lineno"> 5691</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05692"></a><span class="lineno"> 5692</span>&#160;    soap *soap = soap_new(); // new context</div><div class="line"><a name="l05693"></a><span class="lineno"> 5693</span>&#160;    ...</div><div class="line"><a name="l05694"></a><span class="lineno"> 5694</span>&#160;    ns__record *record = soap_new_set_ns__record(</div><div class="line"><a name="l05695"></a><span class="lineno"> 5695</span>&#160;        soap,</div><div class="line"><a name="l05696"></a><span class="lineno"> 5696</span>&#160;        &quot;Joe&quot;,</div><div class="line"><a name="l05697"></a><span class="lineno"> 5697</span>&#160;        soap_make&lt;uint64_t&gt;(soap, 1234567890UL),</div><div class="line"><a name="l05698"></a><span class="lineno"> 5698</span>&#160;        NULL);</div><div class="line"><a name="l05699"></a><span class="lineno"> 5699</span>&#160;    ...</div><div class="line"><a name="l05700"></a><span class="lineno"> 5700</span>&#160;    soap_destroy(soap); // delete record and all other managed instances</div><div class="line"><a name="l05701"></a><span class="lineno"> 5701</span>&#160;    soap_end(soap);     // delete managed soap_malloc&#39;ed heap data</div><div class="line"><a name="l05702"></a><span class="lineno"> 5702</span>&#160;    soap_free(soap);    // delete context</div><div class="line"><a name="l05703"></a><span class="lineno"> 5703</span>&#160;~~~</div><div class="line"><a name="l05704"></a><span class="lineno"> 5704</span>&#160;</div><div class="line"><a name="l05705"></a><span class="lineno"> 5705</span>&#160;All data on the managed heap is mass-deleted with `soap_end(soap)` which must</div><div class="line"><a name="l05706"></a><span class="lineno"> 5706</span>&#160;be called before `soap_done(soap)` or `soap_free(soap)`, which end the use of</div><div class="line"><a name="l05707"></a><span class="lineno"> 5707</span>&#160;the `soap` context and free the context, respectively.  Use</div><div class="line"><a name="l05708"></a><span class="lineno"> 5708</span>&#160;`soap_free(soap)` only when the context is allocated with `soap_new()`.  Use</div><div class="line"><a name="l05709"></a><span class="lineno"> 5709</span>&#160;`soap_done(soap)` only when the context is stack allocated (so cannot be</div><div class="line"><a name="l05710"></a><span class="lineno"> 5710</span>&#160;deleted from the heap).</div><div class="line"><a name="l05711"></a><span class="lineno"> 5711</span>&#160;</div><div class="line"><a name="l05712"></a><span class="lineno"> 5712</span>&#160;The managed heap is checked for memory leaks at run time when the source code</div><div class="line"><a name="l05713"></a><span class="lineno"> 5713</span>&#160;is compiled with option &lt;b&gt;`-DDEBUG`&lt;/b&gt;.</div><div class="line"><a name="l05714"></a><span class="lineno"> 5714</span>&#160;</div><div class="line"><a name="l05715"></a><span class="lineno"> 5715</span>&#160;However, the serializer can serialize any heap, stack, or static allocated</div><div class="line"><a name="l05716"></a><span class="lineno"> 5716</span>&#160;data.  So we can also create a new record as follows:</div><div class="line"><a name="l05717"></a><span class="lineno"> 5717</span>&#160;</div><div class="line"><a name="l05718"></a><span class="lineno"> 5718</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05719"></a><span class="lineno"> 5719</span>&#160;    uint64_t SSN = 1234567890UL;</div><div class="line"><a name="l05720"></a><span class="lineno"> 5720</span>&#160;    ns__record *record = soap_new_set_ns__record(soap, &quot;Joe&quot;, &amp;SSN, NULL);</div><div class="line"><a name="l05721"></a><span class="lineno"> 5721</span>&#160;~~~</div><div class="line"><a name="l05722"></a><span class="lineno"> 5722</span>&#160;</div><div class="line"><a name="l05723"></a><span class="lineno"> 5723</span>&#160;which will be fine to serialize this record as long as the local `SSN`</div><div class="line"><a name="l05724"></a><span class="lineno"> 5724</span>&#160;stack-allocated value remains in scope when invoking the serializer and/or</div><div class="line"><a name="l05725"></a><span class="lineno"> 5725</span>&#160;using `record`.  It does not matter if `soap_destroy` and `soap_end` are called</div><div class="line"><a name="l05726"></a><span class="lineno"> 5726</span>&#160;beyond the scope of `SSN`.</div><div class="line"><a name="l05727"></a><span class="lineno"> 5727</span>&#160;</div><div class="line"><a name="l05728"></a><span class="lineno"> 5728</span>&#160;To facilitate class methods to access the managing context, we can add a soap</div><div class="line"><a name="l05729"></a><span class="lineno"> 5729</span>&#160;context pointer to a class/struct:</div><div class="line"><a name="l05730"></a><span class="lineno"> 5730</span>&#160;</div><div class="line"><a name="l05731"></a><span class="lineno"> 5731</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05732"></a><span class="lineno"> 5732</span>&#160;    class ns__record</div><div class="line"><a name="l05733"></a><span class="lineno"> 5733</span>&#160;    {</div><div class="line"><a name="l05734"></a><span class="lineno"> 5734</span>&#160;     public:</div><div class="line"><a name="l05735"></a><span class="lineno"> 5735</span>&#160;        ...</div><div class="line"><a name="l05736"></a><span class="lineno"> 5736</span>&#160;        void create_more(); // needs a context to create more internal data</div><div class="line"><a name="l05737"></a><span class="lineno"> 5737</span>&#160;      protected:</div><div class="line"><a name="l05738"></a><span class="lineno"> 5738</span>&#160;        struct soap *soap;  // the context that manages this instance, or NULL</div><div class="line"><a name="l05739"></a><span class="lineno"> 5739</span>&#160;    };</div><div class="line"><a name="l05740"></a><span class="lineno"> 5740</span>&#160;~~~</div><div class="line"><a name="l05741"></a><span class="lineno"> 5741</span>&#160;</div><div class="line"><a name="l05742"></a><span class="lineno"> 5742</span>&#160;The `soap` context pointer member of the class is set when invoking</div><div class="line"><a name="l05743"></a><span class="lineno"> 5743</span>&#160;`soap_new_T` (and similar) with a non-NULL context argument that will be</div><div class="line"><a name="l05744"></a><span class="lineno"> 5744</span>&#160;assigned to the `soap` member of the class.</div><div class="line"><a name="l05745"></a><span class="lineno"> 5745</span>&#160;</div><div class="line"><a name="l05746"></a><span class="lineno"> 5746</span>&#160;You can also use a template when an array of pointers to values is required.</div><div class="line"><a name="l05747"></a><span class="lineno"> 5747</span>&#160;To create an array of pointers to values, define the following template:</div><div class="line"><a name="l05748"></a><span class="lineno"> 5748</span>&#160;</div><div class="line"><a name="l05749"></a><span class="lineno"> 5749</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05750"></a><span class="lineno"> 5750</span>&#160;    template&lt;class T&gt;</div><div class="line"><a name="l05751"></a><span class="lineno"> 5751</span>&#160;    T **soap_make_array(struct soap *soap, T* array, int n) throw (std::bad_alloc)</div><div class="line"><a name="l05752"></a><span class="lineno"> 5752</span>&#160;    { </div><div class="line"><a name="l05753"></a><span class="lineno"> 5753</span>&#160;      T **p = (T**)soap_malloc(soap, n * sizeof(T*));</div><div class="line"><a name="l05754"></a><span class="lineno"> 5754</span>&#160;      if (p == NULL)</div><div class="line"><a name="l05755"></a><span class="lineno"> 5755</span>&#160;        throw std::bad_alloc();</div><div class="line"><a name="l05756"></a><span class="lineno"> 5756</span>&#160;      for (int i = 0; i &lt; n; ++i)</div><div class="line"><a name="l05757"></a><span class="lineno"> 5757</span>&#160;        p[i] = &amp;array[i];</div><div class="line"><a name="l05758"></a><span class="lineno"> 5758</span>&#160;      return p;</div><div class="line"><a name="l05759"></a><span class="lineno"> 5759</span>&#160;    }</div><div class="line"><a name="l05760"></a><span class="lineno"> 5760</span>&#160;~~~</div><div class="line"><a name="l05761"></a><span class="lineno"> 5761</span>&#160;</div><div class="line"><a name="l05762"></a><span class="lineno"> 5762</span>&#160;The `array` parameter is a pointer to an array of `n` values.  The template</div><div class="line"><a name="l05763"></a><span class="lineno"> 5763</span>&#160;returns an array of `n` pointers that point to the values in that array:</div><div class="line"><a name="l05764"></a><span class="lineno"> 5764</span>&#160;</div><div class="line"><a name="l05765"></a><span class="lineno"> 5765</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05766"></a><span class="lineno"> 5766</span>&#160;    // create an array of 100 pointers to 100 records</div><div class="line"><a name="l05767"></a><span class="lineno"> 5767</span>&#160;    int n = 100;</div><div class="line"><a name="l05768"></a><span class="lineno"> 5768</span>&#160;    ns__record **precords = soap_make_array(soap, soap_new_ns__record(soap, n), n);</div><div class="line"><a name="l05769"></a><span class="lineno"> 5769</span>&#160;    for (int i = 0; i &lt; n; ++i)</div><div class="line"><a name="l05770"></a><span class="lineno"> 5770</span>&#160;    {</div><div class="line"><a name="l05771"></a><span class="lineno"> 5771</span>&#160;      precords[i]-&gt;name = &quot;...&quot;;</div><div class="line"><a name="l05772"></a><span class="lineno"> 5772</span>&#160;      precords[i]-&gt;SSN = soap_make&lt;uint64_t&gt;(1234567890UL + i);</div><div class="line"><a name="l05773"></a><span class="lineno"> 5773</span>&#160;    }</div><div class="line"><a name="l05774"></a><span class="lineno"> 5774</span>&#160;~~~</div><div class="line"><a name="l05775"></a><span class="lineno"> 5775</span>&#160;</div><div class="line"><a name="l05776"></a><span class="lineno"> 5776</span>&#160;Note that `soap_new_ns__record(soap, n)` returns a pointer to an array of `n`</div><div class="line"><a name="l05777"></a><span class="lineno"> 5777</span>&#160;records, which is then used to create an array of `n` pointers to these records.</div><div class="line"><a name="l05778"></a><span class="lineno"> 5778</span>&#160;</div><div class="line"><a name="l05779"></a><span class="lineno"> 5779</span>&#160;Use the soapcpp2 auto-generated `soap_dup_T` functions to duplicate data into</div><div class="line"><a name="l05780"></a><span class="lineno"> 5780</span>&#160;another `soap` context (this requires &lt;b&gt;`soapcpp2 -Ec`&lt;/b&gt; option &lt;b&gt;`-Ec`&lt;/b&gt; to generate), here shown</div><div class="line"><a name="l05781"></a><span class="lineno"> 5781</span>&#160;for C++ with the second argument `dst` NULL to allocate a new managed object:</div><div class="line"><a name="l05782"></a><span class="lineno"> 5782</span>&#160;</div><div class="line"><a name="l05783"></a><span class="lineno"> 5783</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05784"></a><span class="lineno"> 5784</span>&#160;    soap *other_soap = soap_new(); // another context</div><div class="line"><a name="l05785"></a><span class="lineno"> 5785</span>&#160;    ns__record *other_record = soap_dup_ns__record(other_soap, NULL, record);</div><div class="line"><a name="l05786"></a><span class="lineno"> 5786</span>&#160;    ...</div><div class="line"><a name="l05787"></a><span class="lineno"> 5787</span>&#160;    soap_destroy(other_soap); // delete record and other managed instances</div><div class="line"><a name="l05788"></a><span class="lineno"> 5788</span>&#160;    soap_end(other_soap);     // delete other data (the SSNs on the heap)</div><div class="line"><a name="l05789"></a><span class="lineno"> 5789</span>&#160;    soap_free(other_soap);    // delete context</div><div class="line"><a name="l05790"></a><span class="lineno"> 5790</span>&#160;~~~</div><div class="line"><a name="l05791"></a><span class="lineno"> 5791</span>&#160;</div><div class="line"><a name="l05792"></a><span class="lineno"> 5792</span>&#160;To duplicate base and derived instances when a base class pointer or reference</div><div class="line"><a name="l05793"></a><span class="lineno"> 5793</span>&#160;is provided, use the auto-generated method `T * T::soap_dup(struct soap*)`:</div><div class="line"><a name="l05794"></a><span class="lineno"> 5794</span>&#160;</div><div class="line"><a name="l05795"></a><span class="lineno"> 5795</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05796"></a><span class="lineno"> 5796</span>&#160;    soap *other_soap = soap_new(); // another context</div><div class="line"><a name="l05797"></a><span class="lineno"> 5797</span>&#160;    ns__record *other_record = record-&gt;soap_dup(other_soap);</div><div class="line"><a name="l05798"></a><span class="lineno"> 5798</span>&#160;    ...</div><div class="line"><a name="l05799"></a><span class="lineno"> 5799</span>&#160;    soap_destroy(other_soap); // delete record and other managed instances</div><div class="line"><a name="l05800"></a><span class="lineno"> 5800</span>&#160;    soap_end(other_soap);     // delete other data (the SSNs on the heap)</div><div class="line"><a name="l05801"></a><span class="lineno"> 5801</span>&#160;    soap_free(other_soap);    // delete context</div><div class="line"><a name="l05802"></a><span class="lineno"> 5802</span>&#160;~~~</div><div class="line"><a name="l05803"></a><span class="lineno"> 5803</span>&#160;</div><div class="line"><a name="l05804"></a><span class="lineno"> 5804</span>&#160;The only reason to use another context and not to use the primary `soap`</div><div class="line"><a name="l05805"></a><span class="lineno"> 5805</span>&#160;context is when the primary context must be destroyed together with all of the</div><div class="line"><a name="l05806"></a><span class="lineno"> 5806</span>&#160;objects it manages while some of the objects must be kept alive.  If the</div><div class="line"><a name="l05807"></a><span class="lineno"> 5807</span>&#160;objects that are kept alive contain deep cycles then this is the only option we</div><div class="line"><a name="l05808"></a><span class="lineno"> 5808</span>&#160;have, because deep copy with a managing `soap` context detects and preserves</div><div class="line"><a name="l05809"></a><span class="lineno"> 5809</span>&#160;these cycles unless the `SOAP_XML_TREE` flag is used with the context:</div><div class="line"><a name="l05810"></a><span class="lineno"> 5810</span>&#160;</div><div class="line"><a name="l05811"></a><span class="lineno"> 5811</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05812"></a><span class="lineno"> 5812</span>&#160;    soap *other_soap = soap_new1(SOAP_XML_TREE);             // another context</div><div class="line"><a name="l05813"></a><span class="lineno"> 5813</span>&#160;    ns__record *other_record = record-&gt;soap_dup(other_soap); // deep tree copy</div><div class="line"><a name="l05814"></a><span class="lineno"> 5814</span>&#160;~~~</div><div class="line"><a name="l05815"></a><span class="lineno"> 5815</span>&#160;</div><div class="line"><a name="l05816"></a><span class="lineno"> 5816</span>&#160;The resulting deep copy will be a full copy of the source data structure as a</div><div class="line"><a name="l05817"></a><span class="lineno"> 5817</span>&#160;tree without co-referenced data (i.e. no digraph) and without cycles.  Cycles</div><div class="line"><a name="l05818"></a><span class="lineno"> 5818</span>&#160;are pruned and (one of the) pointers that forms a cycle is repaced by NULL.</div><div class="line"><a name="l05819"></a><span class="lineno"> 5819</span>&#160;</div><div class="line"><a name="l05820"></a><span class="lineno"> 5820</span>&#160;You can also deep copy into unmanaged space and use the auto-generated</div><div class="line"><a name="l05821"></a><span class="lineno"> 5821</span>&#160;`soap_del_T()` function or the `T::soap_del()` method (requires</div><div class="line"><a name="l05822"></a><span class="lineno"> 5822</span>&#160;&lt;b&gt;`soapcpp2 -Ec`&lt;/b&gt; option &lt;b&gt;`-Ec`&lt;/b&gt; to generate) to delete it later,</div><div class="line"><a name="l05823"></a><span class="lineno"> 5823</span>&#160;but we should not do this for any data that has deep cycles in its runtime data</div><div class="line"><a name="l05824"></a><span class="lineno"> 5824</span>&#160;structure graph:</div><div class="line"><a name="l05825"></a><span class="lineno"> 5825</span>&#160;</div><div class="line"><a name="l05826"></a><span class="lineno"> 5826</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05827"></a><span class="lineno"> 5827</span>&#160;    ns__record *other_record = record-&gt;soap_dup(NULL);</div><div class="line"><a name="l05828"></a><span class="lineno"> 5828</span>&#160;    ...</div><div class="line"><a name="l05829"></a><span class="lineno"> 5829</span>&#160;    other_record-&gt;soap_del(); // deep delete record data members</div><div class="line"><a name="l05830"></a><span class="lineno"> 5830</span>&#160;    delete other_record;      // delete the record</div><div class="line"><a name="l05831"></a><span class="lineno"> 5831</span>&#160;~~~</div><div class="line"><a name="l05832"></a><span class="lineno"> 5832</span>&#160;</div><div class="line"><a name="l05833"></a><span class="lineno"> 5833</span>&#160;Cycles in the data structure will lead to non-termination when making unmanaged</div><div class="line"><a name="l05834"></a><span class="lineno"> 5834</span>&#160;deep copies.  Consider for example:</div><div class="line"><a name="l05835"></a><span class="lineno"> 5835</span>&#160;</div><div class="line"><a name="l05836"></a><span class="lineno"> 5836</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05837"></a><span class="lineno"> 5837</span>&#160;    class ns__record</div><div class="line"><a name="l05838"></a><span class="lineno"> 5838</span>&#160;    {</div><div class="line"><a name="l05839"></a><span class="lineno"> 5839</span>&#160;     public:</div><div class="line"><a name="l05840"></a><span class="lineno"> 5840</span>&#160;        const char  *name 1; // required (minOccurs=1)</div><div class="line"><a name="l05841"></a><span class="lineno"> 5841</span>&#160;        uint64_t     SSN;    // required (non-pointer means minOccurs=1)</div><div class="line"><a name="l05842"></a><span class="lineno"> 5842</span>&#160;        ns__record  *spouse; // optional (pointer means minOccurs=1)</div><div class="line"><a name="l05843"></a><span class="lineno"> 5843</span>&#160;    };</div><div class="line"><a name="l05844"></a><span class="lineno"> 5844</span>&#160;~~~</div><div class="line"><a name="l05845"></a><span class="lineno"> 5845</span>&#160;</div><div class="line"><a name="l05846"></a><span class="lineno"> 5846</span>&#160;The code to populate a structure with a mutual spouse relationship:</div><div class="line"><a name="l05847"></a><span class="lineno"> 5847</span>&#160;</div><div class="line"><a name="l05848"></a><span class="lineno"> 5848</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05849"></a><span class="lineno"> 5849</span>&#160;    soap *soap = soap_new();</div><div class="line"><a name="l05850"></a><span class="lineno"> 5850</span>&#160;    ...</div><div class="line"><a name="l05851"></a><span class="lineno"> 5851</span>&#160;    ns__record pers1, pers2;</div><div class="line"><a name="l05852"></a><span class="lineno"> 5852</span>&#160;    pers1.name = &quot;Joe&quot;;</div><div class="line"><a name="l05853"></a><span class="lineno"> 5853</span>&#160;    pers1.SSN = 1234567890;</div><div class="line"><a name="l05854"></a><span class="lineno"> 5854</span>&#160;    pers1.spouse = &amp;pers2;</div><div class="line"><a name="l05855"></a><span class="lineno"> 5855</span>&#160;    pers2.name = &quot;Jane&quot;;</div><div class="line"><a name="l05856"></a><span class="lineno"> 5856</span>&#160;    pers2.SSN = 1987654320;</div><div class="line"><a name="l05857"></a><span class="lineno"> 5857</span>&#160;    pers2.spouse = &amp;pers1;</div><div class="line"><a name="l05858"></a><span class="lineno"> 5858</span>&#160;    ...</div><div class="line"><a name="l05859"></a><span class="lineno"> 5859</span>&#160;    ns__record *pers3 = soap_dup_ns__record(NULL, NULL, &amp;pers1); // BAD</div><div class="line"><a name="l05860"></a><span class="lineno"> 5860</span>&#160;    ns__record *pers4 = soap_dup_ns__record(soap, NULL, &amp;pers1); // OK</div><div class="line"><a name="l05861"></a><span class="lineno"> 5861</span>&#160;    soap_set_mode(soap, SOAP_XML_TREE);</div><div class="line"><a name="l05862"></a><span class="lineno"> 5862</span>&#160;    ns__record *pers5 = soap_dup_ns__record(soap, NULL, &amp;pers1); // OK</div><div class="line"><a name="l05863"></a><span class="lineno"> 5863</span>&#160;~~~</div><div class="line"><a name="l05864"></a><span class="lineno"> 5864</span>&#160;</div><div class="line"><a name="l05865"></a><span class="lineno"> 5865</span>&#160;The serializer can serialize any heap, stack, or static allocated data, such as</div><div class="line"><a name="l05866"></a><span class="lineno"> 5866</span>&#160;shown in the code shown above.  So we can serialize the stack-allocated `pers1`</div><div class="line"><a name="l05867"></a><span class="lineno"> 5867</span>&#160;record as follows:</div><div class="line"><a name="l05868"></a><span class="lineno"> 5868</span>&#160;</div><div class="line"><a name="l05869"></a><span class="lineno"> 5869</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05870"></a><span class="lineno"> 5870</span>&#160;    FILE *fp = fopen(&quot;record.xml&quot;, &quot;w&quot;);</div><div class="line"><a name="l05871"></a><span class="lineno"> 5871</span>&#160;    if (fp != NULL)</div><div class="line"><a name="l05872"></a><span class="lineno"> 5872</span>&#160;    {</div><div class="line"><a name="l05873"></a><span class="lineno"> 5873</span>&#160;      soap-&gt;sendfd = fileno(fp);           // file descriptor to write to</div><div class="line"><a name="l05874"></a><span class="lineno"> 5874</span>&#160;      soap_set_mode(soap, SOAP_XML_GRAPH); // support id-ref w/o requiring SOAP</div><div class="line"><a name="l05875"></a><span class="lineno"> 5875</span>&#160;      soap_clr_mode(soap, SOAP_XML_TREE);  // if set, clear</div><div class="line"><a name="l05876"></a><span class="lineno"> 5876</span>&#160;      if (soap_write_ns__record(soap, &amp;pers1))</div><div class="line"><a name="l05877"></a><span class="lineno"> 5877</span>&#160;        ... // handle IO error</div><div class="line"><a name="l05878"></a><span class="lineno"> 5878</span>&#160;          fclose(fp);</div><div class="line"><a name="l05879"></a><span class="lineno"> 5879</span>&#160;      soap-&gt;sendfd = -1;                   // block further writing</div><div class="line"><a name="l05880"></a><span class="lineno"> 5880</span>&#160;    }</div><div class="line"><a name="l05881"></a><span class="lineno"> 5881</span>&#160;~~~</div><div class="line"><a name="l05882"></a><span class="lineno"> 5882</span>&#160;</div><div class="line"><a name="l05883"></a><span class="lineno"> 5883</span>&#160;which produces an XML document record.xml that is similar to:</div><div class="line"><a name="l05884"></a><span class="lineno"> 5884</span>&#160;</div><div class="line"><a name="l05885"></a><span class="lineno"> 5885</span>&#160;&lt;div class=&quot;alt&quot;&gt;</div><div class="line"><a name="l05886"></a><span class="lineno"> 5886</span>&#160;~~~{.xml}</div><div class="line"><a name="l05887"></a><span class="lineno"> 5887</span>&#160;    &lt;ns:record xmlns:ns=&quot;urn:types&quot; id=&quot;Joe&quot;&gt;</div><div class="line"><a name="l05888"></a><span class="lineno"> 5888</span>&#160;      &lt;name&gt;Joe&lt;/name&gt;</div><div class="line"><a name="l05889"></a><span class="lineno"> 5889</span>&#160;      &lt;SSN&gt;1234567890&lt;/SSN&gt;</div><div class="line"><a name="l05890"></a><span class="lineno"> 5890</span>&#160;      &lt;spouse id=&quot;Jane&quot;&gt;</div><div class="line"><a name="l05891"></a><span class="lineno"> 5891</span>&#160;        &lt;name&gt;Jane&lt;/name&gt;</div><div class="line"><a name="l05892"></a><span class="lineno"> 5892</span>&#160;        &lt;SSN&gt;1987654320&lt;/SSN&gt;</div><div class="line"><a name="l05893"></a><span class="lineno"> 5893</span>&#160;        &lt;spouse ref=&quot;#Joe&quot;/&gt;</div><div class="line"><a name="l05894"></a><span class="lineno"> 5894</span>&#160;      &lt;/spouse&gt;</div><div class="line"><a name="l05895"></a><span class="lineno"> 5895</span>&#160;    &lt;/ns:record&gt;</div><div class="line"><a name="l05896"></a><span class="lineno"> 5896</span>&#160;~~~</div><div class="line"><a name="l05897"></a><span class="lineno"> 5897</span>&#160;&lt;/div&gt;</div><div class="line"><a name="l05898"></a><span class="lineno"> 5898</span>&#160;</div><div class="line"><a name="l05899"></a><span class="lineno"> 5899</span>&#160;Deserialization of an XML document with a SOAP 1.1/1.2 encoded id-ref graph</div><div class="line"><a name="l05900"></a><span class="lineno"> 5900</span>&#160;leads to the same non-termination problem when we later try to copy the data</div><div class="line"><a name="l05901"></a><span class="lineno"> 5901</span>&#160;into unmanaged space:</div><div class="line"><a name="l05902"></a><span class="lineno"> 5902</span>&#160;    </div><div class="line"><a name="l05903"></a><span class="lineno"> 5903</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05904"></a><span class="lineno"> 5904</span>&#160;    soap *soap = soap_new1(SOAP_XML_GRAPH); // support id-ref w/o SOAP</div><div class="line"><a name="l05905"></a><span class="lineno"> 5905</span>&#160;    ...</div><div class="line"><a name="l05906"></a><span class="lineno"> 5906</span>&#160;    ns__record pers1;</div><div class="line"><a name="l05907"></a><span class="lineno"> 5907</span>&#160;    FILE *fp = fopen(&quot;record.xml&quot;, &quot;r&quot;);</div><div class="line"><a name="l05908"></a><span class="lineno"> 5908</span>&#160;    if (fp != NULL)</div><div class="line"><a name="l05909"></a><span class="lineno"> 5909</span>&#160;    {</div><div class="line"><a name="l05910"></a><span class="lineno"> 5910</span>&#160;      soap-&gt;recvfd = fileno(fp);            // file descriptor to read from</div><div class="line"><a name="l05911"></a><span class="lineno"> 5911</span>&#160;      if (soap_read_ns__record(soap, &amp;pers1))</div><div class="line"><a name="l05912"></a><span class="lineno"> 5912</span>&#160;        ... // handle IO error</div><div class="line"><a name="l05913"></a><span class="lineno"> 5913</span>&#160;      fclose(fp);</div><div class="line"><a name="l05914"></a><span class="lineno"> 5914</span>&#160;      soap-&gt;recvfd = -1;                    // block further reading</div><div class="line"><a name="l05915"></a><span class="lineno"> 5915</span>&#160;    }</div><div class="line"><a name="l05916"></a><span class="lineno"> 5916</span>&#160;    ...</div><div class="line"><a name="l05917"></a><span class="lineno"> 5917</span>&#160;    ns__record *pers3 = soap_dup_ns__record(NULL, NULL, &amp;pers1); // BAD</div><div class="line"><a name="l05918"></a><span class="lineno"> 5918</span>&#160;    ns__record *pers4 = soap_dup_ns__record(soap, NULL, &amp;pers1); // OK</div><div class="line"><a name="l05919"></a><span class="lineno"> 5919</span>&#160;    soap_set_mode(soap, SOAP_XML_TREE);</div><div class="line"><a name="l05920"></a><span class="lineno"> 5920</span>&#160;    ns__record *pers5 = soap_dup_ns__record(soap, NULL, &amp;pers1); // OK</div><div class="line"><a name="l05921"></a><span class="lineno"> 5921</span>&#160;~~~</div><div class="line"><a name="l05922"></a><span class="lineno"> 5922</span>&#160;</div><div class="line"><a name="l05923"></a><span class="lineno"> 5923</span>&#160;Copying data with `soap_dup_T(soap)` into managed space is always safe.  Copying</div><div class="line"><a name="l05924"></a><span class="lineno"> 5924</span>&#160;into unmanaged space requires diligence.  But deleting unmanaged data is easy</div><div class="line"><a name="l05925"></a><span class="lineno"> 5925</span>&#160;with `soap_del_T()`.</div><div class="line"><a name="l05926"></a><span class="lineno"> 5926</span>&#160;</div><div class="line"><a name="l05927"></a><span class="lineno"> 5927</span>&#160;You can also use `soap_del_T()` to delete structures in C++, but only if these</div><div class="line"><a name="l05928"></a><span class="lineno"> 5928</span>&#160;structures are created with `new` (and `new []` for arrays when applicable) for</div><div class="line"><a name="l05929"></a><span class="lineno"> 5929</span>&#160;classes, structs, and class templates and with `malloc` for anything else, and</div><div class="line"><a name="l05930"></a><span class="lineno"> 5930</span>&#160;the structures do NOT contain pointers to stack and static data.</div><div class="line"><a name="l05931"></a><span class="lineno"> 5931</span>&#160;</div><div class="line"><a name="l05932"></a><span class="lineno"> 5932</span>&#160;You can unlink one or more allocated objects from the managed heap to allow the</div><div class="line"><a name="l05933"></a><span class="lineno"> 5933</span>&#160;object to live after `soap_destroy(soap)` and `soap_end(soap)` by using:</div><div class="line"><a name="l05934"></a><span class="lineno"> 5934</span>&#160;</div><div class="line"><a name="l05935"></a><span class="lineno"> 5935</span>&#160;- `void soap_unlink(struct soap *soap, void *ptr)`</div><div class="line"><a name="l05936"></a><span class="lineno"> 5936</span>&#160;</div><div class="line"><a name="l05937"></a><span class="lineno"> 5937</span>&#160;The unlinked heap-allocated data pointed to by `ptr` can be accessed after</div><div class="line"><a name="l05938"></a><span class="lineno"> 5938</span>&#160;`soap_destroy(soap)` and `soap_end(soap)`.  Do not forget to free the data with</div><div class="line"><a name="l05939"></a><span class="lineno"> 5939</span>&#160;`delete ptr` (C++ class instance only) or with `free(ptr)` (non-class data).</div><div class="line"><a name="l05940"></a><span class="lineno"> 5940</span>&#160;Be aware that `soap_unlink(soap, ptr)` does not perform a deep unlinkage.  If</div><div class="line"><a name="l05941"></a><span class="lineno"> 5941</span>&#160;`ptr` is a struct or class, pointer members will become invalid when pointing</div><div class="line"><a name="l05942"></a><span class="lineno"> 5942</span>&#160;to objects on the managed heap.  Use `soap_unlink(soap, ptr-&gt;member)` to unlink</div><div class="line"><a name="l05943"></a><span class="lineno"> 5943</span>&#160;`member` as well.</div><div class="line"><a name="l05944"></a><span class="lineno"> 5944</span>&#160;</div><div class="line"><a name="l05945"></a><span class="lineno"> 5945</span>&#160;Finally, when data is allocated in managed memory heap space, either explicitly</div><div class="line"><a name="l05946"></a><span class="lineno"> 5946</span>&#160;with the allocation functions shown above or by the soapcpp2-generated</div><div class="line"><a name="l05947"></a><span class="lineno"> 5947</span>&#160;deserializers, you can delegate the management and deletion of this data to</div><div class="line"><a name="l05948"></a><span class="lineno"> 5948</span>&#160;another `soap` context.  That context will be responsible to delete the data</div><div class="line"><a name="l05949"></a><span class="lineno"> 5949</span>&#160;with `soap_destroy(soap)` and `soap_end(soap)` later:</div><div class="line"><a name="l05950"></a><span class="lineno"> 5950</span>&#160;</div><div class="line"><a name="l05951"></a><span class="lineno"> 5951</span>&#160;- `void delegate_deletion(struct soap *soap_from, struct soap *soap_to)`</div><div class="line"><a name="l05952"></a><span class="lineno"> 5952</span>&#160;</div><div class="line"><a name="l05953"></a><span class="lineno"> 5953</span>&#160;This allows the `soap_from` context to be deleted with `soap_free(soap_from)`</div><div class="line"><a name="l05954"></a><span class="lineno"> 5954</span>&#160;(assuming it is allocated with `soap_new()`, use `soap_done(soap_from)` when</div><div class="line"><a name="l05955"></a><span class="lineno"> 5955</span>&#160;`soap_from` is stack-allocated) while the managed data remains intact.  You</div><div class="line"><a name="l05956"></a><span class="lineno"> 5956</span>&#160;can use this function any time, to delegate management and deletion to another</div><div class="line"><a name="l05957"></a><span class="lineno"> 5957</span>&#160;context `soap_to` and then continue with the current context.  You can also use</div><div class="line"><a name="l05958"></a><span class="lineno"> 5958</span>&#160;different source `soap_from` contexts to delegate management and deletion to</div><div class="line"><a name="l05959"></a><span class="lineno"> 5959</span>&#160;the other `soap_to` context.  To mass delete all managed data, use</div><div class="line"><a name="l05960"></a><span class="lineno"> 5960</span>&#160;`soap_destroy(soap_to)` followed by `soap_end(soap_to)`.</div><div class="line"><a name="l05961"></a><span class="lineno"> 5961</span>&#160;</div><div class="line"><a name="l05962"></a><span class="lineno"> 5962</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l05963"></a><span class="lineno"> 5963</span>&#160;</div><div class="line"><a name="l05964"></a><span class="lineno"> 5964</span>&#160;Context flags to initialize the soap struct                             {#flags}</div><div class="line"><a name="l05965"></a><span class="lineno"> 5965</span>&#160;===========================================</div><div class="line"><a name="l05966"></a><span class="lineno"> 5966</span>&#160;</div><div class="line"><a name="l05967"></a><span class="lineno"> 5967</span>&#160;There are several `soap` context initialization flags and context mode flags to</div><div class="line"><a name="l05968"></a><span class="lineno"> 5968</span>&#160;control XML serialization at runtime.  The flags are set with `soap_new1()` to</div><div class="line"><a name="l05969"></a><span class="lineno"> 5969</span>&#160;allocate and initialize a new context:</div><div class="line"><a name="l05970"></a><span class="lineno"> 5970</span>&#160;</div><div class="line"><a name="l05971"></a><span class="lineno"> 5971</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05972"></a><span class="lineno"> 5972</span>&#160;    struct soap *soap = soap_new1(flag1 | flag2 | ... | flagn);</div><div class="line"><a name="l05973"></a><span class="lineno"> 5973</span>&#160;    ...</div><div class="line"><a name="l05974"></a><span class="lineno"> 5974</span>&#160;    soap_destroy(soap); // delete objects</div><div class="line"><a name="l05975"></a><span class="lineno"> 5975</span>&#160;    soap_end(soap);     // delete other data and temp data</div><div class="line"><a name="l05976"></a><span class="lineno"> 5976</span>&#160;    soap_free(soap);    // free context</div><div class="line"><a name="l05977"></a><span class="lineno"> 5977</span>&#160;~~~</div><div class="line"><a name="l05978"></a><span class="lineno"> 5978</span>&#160;</div><div class="line"><a name="l05979"></a><span class="lineno"> 5979</span>&#160;and with `soap_init1()` for stack-allocated contexts:</div><div class="line"><a name="l05980"></a><span class="lineno"> 5980</span>&#160;</div><div class="line"><a name="l05981"></a><span class="lineno"> 5981</span>&#160;~~~{.cpp}</div><div class="line"><a name="l05982"></a><span class="lineno"> 5982</span>&#160;    struct soap soap;</div><div class="line"><a name="l05983"></a><span class="lineno"> 5983</span>&#160;    soap_init1(&amp;soap, flag1 | flag2 | ... | flagn);</div><div class="line"><a name="l05984"></a><span class="lineno"> 5984</span>&#160;    ...</div><div class="line"><a name="l05985"></a><span class="lineno"> 5985</span>&#160;    soap_destroy(&amp;soap); // delete objects</div><div class="line"><a name="l05986"></a><span class="lineno"> 5986</span>&#160;    soap_end(&amp;soap);     // delete other data and temp data</div><div class="line"><a name="l05987"></a><span class="lineno"> 5987</span>&#160;    soap_done(&amp;soap);    // clear context</div><div class="line"><a name="l05988"></a><span class="lineno"> 5988</span>&#160;~~~</div><div class="line"><a name="l05989"></a><span class="lineno"> 5989</span>&#160;</div><div class="line"><a name="l05990"></a><span class="lineno"> 5990</span>&#160;where `flag1`, `flag2`, ..., `flagn` is one of:</div><div class="line"><a name="l05991"></a><span class="lineno"> 5991</span>&#160;</div><div class="line"><a name="l05992"></a><span class="lineno"> 5992</span>&#160;- `SOAP_C_UTFSTRING`: enables all `std::string` and `char*` strings to</div><div class="line"><a name="l05993"></a><span class="lineno"> 5993</span>&#160;  contain UTF-8 content.  This option is recommended.</div><div class="line"><a name="l05994"></a><span class="lineno"> 5994</span>&#160;</div><div class="line"><a name="l05995"></a><span class="lineno"> 5995</span>&#160;- `SOAP_C_NILSTRING`: treat empty strings as if they were NULL pointers, i.e.</div><div class="line"><a name="l05996"></a><span class="lineno"> 5996</span>&#160;  omits elements and attributes when empty.</div><div class="line"><a name="l05997"></a><span class="lineno"> 5997</span>&#160;</div><div class="line"><a name="l05998"></a><span class="lineno"> 5998</span>&#160;- `SOAP_XML_STRICT`: strictly validates XML while deserializing.  Should not be</div><div class="line"><a name="l05999"></a><span class="lineno"> 5999</span>&#160;  used together with SOAP 1.1/1.2 encoding style of messaging.  Use</div><div class="line"><a name="l06000"></a><span class="lineno"> 6000</span>&#160;  &lt;b&gt;`soapcpp2 -s`&lt;/b&gt; option &lt;b&gt;`-s`&lt;/b&gt; to hard code `SOAP_XML_STRICT` in the</div><div class="line"><a name="l06001"></a><span class="lineno"> 6001</span>&#160;  generated serializers.  Not recommended with SOAP 1.1/1.2 encoding style</div><div class="line"><a name="l06002"></a><span class="lineno"> 6002</span>&#160;  messaging.</div><div class="line"><a name="l06003"></a><span class="lineno"> 6003</span>&#160;</div><div class="line"><a name="l06004"></a><span class="lineno"> 6004</span>&#160;- `SOAP_XML_INDENT`: produces indented XML.</div><div class="line"><a name="l06005"></a><span class="lineno"> 6005</span>&#160;</div><div class="line"><a name="l06006"></a><span class="lineno"> 6006</span>&#160;- `SOAP_XML_CANONICAL`: c14n canonocalization, removes unused `xmlns` bindings</div><div class="line"><a name="l06007"></a><span class="lineno"> 6007</span>&#160;  and adds them to appropriate places by applying c14n normalization rules.</div><div class="line"><a name="l06008"></a><span class="lineno"> 6008</span>&#160;  Should not be used together with SOAP 1.1/1.2 encoding style messaging.</div><div class="line"><a name="l06009"></a><span class="lineno"> 6009</span>&#160;</div><div class="line"><a name="l06010"></a><span class="lineno"> 6010</span>&#160;- `SOAP_XML_TREE`: write tree XML without id-ref, while pruning data structure</div><div class="line"><a name="l06011"></a><span class="lineno"> 6011</span>&#160;  cycles to prevent nontermination of the serializer for cyclic structures.</div><div class="line"><a name="l06012"></a><span class="lineno"> 6012</span>&#160;</div><div class="line"><a name="l06013"></a><span class="lineno"> 6013</span>&#160;- `SOAP_XML_GRAPH`: write graph (digraph and cyclic graphs with shared pointers</div><div class="line"><a name="l06014"></a><span class="lineno"> 6014</span>&#160;  to objects) using id-ref attributes.  That is, XML with SOAP multi-ref</div><div class="line"><a name="l06015"></a><span class="lineno"> 6015</span>&#160;  encoded id-ref elements.  This is a structure-preserving serialization format,</div><div class="line"><a name="l06016"></a><span class="lineno"> 6016</span>&#160;  because co-referenced data and also cyclic relations are accurately represented.</div><div class="line"><a name="l06017"></a><span class="lineno"> 6017</span>&#160;</div><div class="line"><a name="l06018"></a><span class="lineno"> 6018</span>&#160;- `SOAP_XML_DEFAULTNS`: uses xmlns default namespace declarations, assuming</div><div class="line"><a name="l06019"></a><span class="lineno"> 6019</span>&#160;   that the schema attribute form is &quot;qualified&quot; by default (be warned if it is</div><div class="line"><a name="l06020"></a><span class="lineno"> 6020</span>&#160;   not, since attributes in the null namespace will get bound to namespaces!).</div><div class="line"><a name="l06021"></a><span class="lineno"> 6021</span>&#160;</div><div class="line"><a name="l06022"></a><span class="lineno"> 6022</span>&#160;- `SOAP_XML_NIL`: emit empty element with &lt;i&gt;`xsi:nil`&lt;/i&gt; for all NULL pointers</div><div class="line"><a name="l06023"></a><span class="lineno"> 6023</span>&#160;  serialized.</div><div class="line"><a name="l06024"></a><span class="lineno"> 6024</span>&#160;</div><div class="line"><a name="l06025"></a><span class="lineno"> 6025</span>&#160;- `SOAP_XML_IGNORENS`: the XML parser ignores XML namespaces, i.e. element and</div><div class="line"><a name="l06026"></a><span class="lineno"> 6026</span>&#160;  attribute tag names match independent of their namespace.</div><div class="line"><a name="l06027"></a><span class="lineno"> 6027</span>&#160;</div><div class="line"><a name="l06028"></a><span class="lineno"> 6028</span>&#160;- `SOAP_XML_NOTYPE`: removes all &lt;i&gt;`xsi:type`&lt;/i&gt; attribuation.  This option is usually</div><div class="line"><a name="l06029"></a><span class="lineno"> 6029</span>&#160;  not needed unless the receiver rejects all &lt;i&gt;`xsi:type`&lt;/i&gt; attributes.  This option</div><div class="line"><a name="l06030"></a><span class="lineno"> 6030</span>&#160;  may affect the quality of the deserializer, which relies on &lt;i&gt;`xsi:type`&lt;/i&gt;</div><div class="line"><a name="l06031"></a><span class="lineno"> 6031</span>&#160;  attributes to distinguish base class instances from derived class instances</div><div class="line"><a name="l06032"></a><span class="lineno"> 6032</span>&#160;  transported in the XML payloads.</div><div class="line"><a name="l06033"></a><span class="lineno"> 6033</span>&#160;</div><div class="line"><a name="l06034"></a><span class="lineno"> 6034</span>&#160;- `SOAP_IO_CHUNK`: to enable HTTP chunked transfers.</div><div class="line"><a name="l06035"></a><span class="lineno"> 6035</span>&#160;</div><div class="line"><a name="l06036"></a><span class="lineno"> 6036</span>&#160;- `SOAP_IO_STORE`: full buffering of outbound messages.</div><div class="line"><a name="l06037"></a><span class="lineno"> 6037</span>&#160;</div><div class="line"><a name="l06038"></a><span class="lineno"> 6038</span>&#160;- `SOAP_ENC_ZLIB`: compress messages, requires compiling with option &lt;b&gt;`-DWITH_GZIP`&lt;/b&gt; and</div><div class="line"><a name="l06039"></a><span class="lineno"> 6039</span>&#160;   linking with zlib using option &lt;b&gt;`-lz`&lt;/b&gt;.</div><div class="line"><a name="l06040"></a><span class="lineno"> 6040</span>&#160;</div><div class="line"><a name="l06041"></a><span class="lineno"> 6041</span>&#160;- `SOAP_ENC_MIME`: enable MIME attachments, see</div><div class="line"><a name="l06042"></a><span class="lineno"> 6042</span>&#160;  [DIME/MIME/MTOM attachment binary types](#toxsd10-3).</div><div class="line"><a name="l06043"></a><span class="lineno"> 6043</span>&#160;</div><div class="line"><a name="l06044"></a><span class="lineno"> 6044</span>&#160;- `SOAP_ENC_MTOM`: enable MTOM attachments, see</div><div class="line"><a name="l06045"></a><span class="lineno"> 6045</span>&#160;  [DIME/MIME/MTOM attachment binary types](#toxsd10-3).</div><div class="line"><a name="l06046"></a><span class="lineno"> 6046</span>&#160;</div><div class="line"><a name="l06047"></a><span class="lineno"> 6047</span>&#160;@note C++ Web service proxy and service classes have their own `soap` context, either</div><div class="line"><a name="l06048"></a><span class="lineno"> 6048</span>&#160;as a base class (with &lt;b&gt;`soapcpp2 -i`&lt;/b&gt; option &lt;b&gt;`-i`&lt;/b&gt;) or as a pointer member `soap` that points to</div><div class="line"><a name="l06049"></a><span class="lineno"> 6049</span>&#160;a context (with &lt;b&gt;`soapcpp2 -j`&lt;/b&gt; option &lt;b&gt;`-j`&lt;/b&gt;).  These contexts are allocated when the proxy or</div><div class="line"><a name="l06050"></a><span class="lineno"> 6050</span>&#160;service is instantiated with context flags that are passed to the constructor.</div><div class="line"><a name="l06051"></a><span class="lineno"> 6051</span>&#160;</div><div class="line"><a name="l06052"></a><span class="lineno"> 6052</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l06053"></a><span class="lineno"> 6053</span>&#160;</div><div class="line"><a name="l06054"></a><span class="lineno"> 6054</span>&#160;Context parameter settings                                             {#params}</div><div class="line"><a name="l06055"></a><span class="lineno"> 6055</span>&#160;==========================</div><div class="line"><a name="l06056"></a><span class="lineno"> 6056</span>&#160;</div><div class="line"><a name="l06057"></a><span class="lineno"> 6057</span>&#160;After allocation and initializtion of a `soap` context, several context</div><div class="line"><a name="l06058"></a><span class="lineno"> 6058</span>&#160;parameters can be set (some parameters may require 2.8.31 or greater):</div><div class="line"><a name="l06059"></a><span class="lineno"> 6059</span>&#160;</div><div class="line"><a name="l06060"></a><span class="lineno"> 6060</span>&#160;- `unsigned int soap::maxlevel` is the maximum XML nesting depth levels that</div><div class="line"><a name="l06061"></a><span class="lineno"> 6061</span>&#160;  the parser permits.  Default initialized to `SOAP_MAXLEVEL` (10000), which is</div><div class="line"><a name="l06062"></a><span class="lineno"> 6062</span>&#160;  a redefinable macro in &lt;i&gt;`gsoap/stdsoap2.h`&lt;/i&gt;.  Set `soap::maxlevel` to a</div><div class="line"><a name="l06063"></a><span class="lineno"> 6063</span>&#160;  lower value to restrict XML parsing nesting depth.</div><div class="line"><a name="l06064"></a><span class="lineno"> 6064</span>&#160;</div><div class="line"><a name="l06065"></a><span class="lineno"> 6065</span>&#160;- `long soap::maxlength` is the maximum string content length if not already</div><div class="line"><a name="l06066"></a><span class="lineno"> 6066</span>&#160;  constrained by an XML schema validation `maxLength` constraint.  Zero means</div><div class="line"><a name="l06067"></a><span class="lineno"> 6067</span>&#160;  unlimited string lengths are permitted (unless restricted by XML schema</div><div class="line"><a name="l06068"></a><span class="lineno"> 6068</span>&#160;  `maxLength`).  Default initialized to `SOAP_MAXLENGTH` (0), which is a</div><div class="line"><a name="l06069"></a><span class="lineno"> 6069</span>&#160;  redefinable macro in &lt;i&gt;`gsoap/stdsoap2.h`&lt;/i&gt;.  Set `soap::maxlength` to a</div><div class="line"><a name="l06070"></a><span class="lineno"> 6070</span>&#160;  positive value to restrict the number of (wide) characters in strings parsed,</div><div class="line"><a name="l06071"></a><span class="lineno"> 6071</span>&#160;  restrict hexBinary byte length, and restrict base64Binary byte length.</div><div class="line"><a name="l06072"></a><span class="lineno"> 6072</span>&#160;</div><div class="line"><a name="l06073"></a><span class="lineno"> 6073</span>&#160;- `size_t soap::maxoccurs` is the maximum number of array or container elements</div><div class="line"><a name="l06074"></a><span class="lineno"> 6074</span>&#160;  permitted by the parser.  Must be greater than zero (0).  Default initialized</div><div class="line"><a name="l06075"></a><span class="lineno"> 6075</span>&#160;  to `SOAP_MAXOCCURS` (100000), which is a redefinable macro in</div><div class="line"><a name="l06076"></a><span class="lineno"> 6076</span>&#160;  &lt;i&gt;`gsoap/stdsoap2.h`&lt;/i&gt;.  Set `soap::maxoccurs` to a positive value to</div><div class="line"><a name="l06077"></a><span class="lineno"> 6077</span>&#160;  restrict the number of array and container elements that can be parsed.</div><div class="line"><a name="l06078"></a><span class="lineno"> 6078</span>&#160;</div><div class="line"><a name="l06079"></a><span class="lineno"> 6079</span>&#160;- `soap::version` is the SOAP version used, with 0 for non-SOAP, 1 for SOAP1.1,</div><div class="line"><a name="l06080"></a><span class="lineno"> 6080</span>&#160;  and 2 for SOAP1.2.  This value is normally set by web service operations, and</div><div class="line"><a name="l06081"></a><span class="lineno"> 6081</span>&#160;  is otherwise 0 (non-SOAP).  Use `soap_set_version(struct soap*, short)` to</div><div class="line"><a name="l06082"></a><span class="lineno"> 6082</span>&#160;  set the value.  This controls XML namespaces and SOAP id-ref serialization</div><div class="line"><a name="l06083"></a><span class="lineno"> 6083</span>&#160;  when applicable with an encodingStyle (see below).</div><div class="line"><a name="l06084"></a><span class="lineno"> 6084</span>&#160;</div><div class="line"><a name="l06085"></a><span class="lineno"> 6085</span>&#160;- `const char *soap::encodingStyle` is a string that is used with SOAP</div><div class="line"><a name="l06086"></a><span class="lineno"> 6086</span>&#160;  encoding, normally NULL for non-SOAP XML.  Set this string to &quot;&quot; (empty</div><div class="line"><a name="l06087"></a><span class="lineno"> 6087</span>&#160;  string) to enable SOAP encoding style, which supports id-ref graph</div><div class="line"><a name="l06088"></a><span class="lineno"> 6088</span>&#160;  serialization (see also the `SOAP_XML_GRAPH` [context flag](#flags)).</div><div class="line"><a name="l06089"></a><span class="lineno"> 6089</span>&#160;</div><div class="line"><a name="l06090"></a><span class="lineno"> 6090</span>&#160;- `int soap::recvfd` is the file descriptor to read and parse source data from.</div><div class="line"><a name="l06091"></a><span class="lineno"> 6091</span>&#160;  Default initialized to 0 (stdin).  See also [input and output](#io).</div><div class="line"><a name="l06092"></a><span class="lineno"> 6092</span>&#160;</div><div class="line"><a name="l06093"></a><span class="lineno"> 6093</span>&#160;- `int soap::sendfd` is the file descriptor to write data to.  Default</div><div class="line"><a name="l06094"></a><span class="lineno"> 6094</span>&#160;  initialized to 1 (stdout).  See also [input and output](#io).</div><div class="line"><a name="l06095"></a><span class="lineno"> 6095</span>&#160;</div><div class="line"><a name="l06096"></a><span class="lineno"> 6096</span>&#160;- `const char *is` for C: string to read and parse source data from, overriding</div><div class="line"><a name="l06097"></a><span class="lineno"> 6097</span>&#160;  the `recvfd` source.  Normally NULL.  This value must be reset to NULL or</div><div class="line"><a name="l06098"></a><span class="lineno"> 6098</span>&#160;  the parser will continue to read from this string content until the NUL</div><div class="line"><a name="l06099"></a><span class="lineno"> 6099</span>&#160;  character.  See also [input and output](#io).</div><div class="line"><a name="l06100"></a><span class="lineno"> 6100</span>&#160;</div><div class="line"><a name="l06101"></a><span class="lineno"> 6101</span>&#160;- `std::istream *is` for C++: an input stream to read and parse source data</div><div class="line"><a name="l06102"></a><span class="lineno"> 6102</span>&#160;  from, overriding the `recvfd` source.  Normally NULL.  This value must be</div><div class="line"><a name="l06103"></a><span class="lineno"> 6103</span>&#160;  reset to NULL or the parser will continue to read from this stream until EOF.</div><div class="line"><a name="l06104"></a><span class="lineno"> 6104</span>&#160;  See also [input and output](#io).</div><div class="line"><a name="l06105"></a><span class="lineno"> 6105</span>&#160;</div><div class="line"><a name="l06106"></a><span class="lineno"> 6106</span>&#160;- `const char **os` for C: points to a string (a `const char *`) that will be</div><div class="line"><a name="l06107"></a><span class="lineno"> 6107</span>&#160;  set to point to the string output.  Normally NULL.  This value must be reset</div><div class="line"><a name="l06108"></a><span class="lineno"> 6108</span>&#160;  to NULL or the next output will result in reassigning the pointer to point to</div><div class="line"><a name="l06109"></a><span class="lineno"> 6109</span>&#160;  the next string that is output.  The strings are automatically deallocated by</div><div class="line"><a name="l06110"></a><span class="lineno"> 6110</span>&#160;  `soap_end(soap)`.  See also [input and output](#io).</div><div class="line"><a name="l06111"></a><span class="lineno"> 6111</span>&#160;</div><div class="line"><a name="l06112"></a><span class="lineno"> 6112</span>&#160;- `std::ostream *os` for C++: an output stream to write output to.  Normally</div><div class="line"><a name="l06113"></a><span class="lineno"> 6113</span>&#160;  NULL.  This value must be reste to NULL or the next output will be send to</div><div class="line"><a name="l06114"></a><span class="lineno"> 6114</span>&#160;  this stream.  See also [input and output](#io).</div><div class="line"><a name="l06115"></a><span class="lineno"> 6115</span>&#160;</div><div class="line"><a name="l06116"></a><span class="lineno"> 6116</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l06117"></a><span class="lineno"> 6117</span>&#160;</div><div class="line"><a name="l06118"></a><span class="lineno"> 6118</span>&#160;Error handling and reporting                                           {#errors}</div><div class="line"><a name="l06119"></a><span class="lineno"> 6119</span>&#160;============================</div><div class="line"><a name="l06120"></a><span class="lineno"> 6120</span>&#160;</div><div class="line"><a name="l06121"></a><span class="lineno"> 6121</span>&#160;The gSOAP API functions return `SOAP_OK` (zero) or a non-zero error code.  The</div><div class="line"><a name="l06122"></a><span class="lineno"> 6122</span>&#160;error code is stored in `int soap::error` of the current `soap` context.</div><div class="line"><a name="l06123"></a><span class="lineno"> 6123</span>&#160;Error messages can be displayed with:</div><div class="line"><a name="l06124"></a><span class="lineno"> 6124</span>&#160;</div><div class="line"><a name="l06125"></a><span class="lineno"> 6125</span>&#160;- `void soap_stream_fault(struct soap*, std::ostream &amp;os)` for C++ only, prints</div><div class="line"><a name="l06126"></a><span class="lineno"> 6126</span>&#160;  the error message to an output stream.</div><div class="line"><a name="l06127"></a><span class="lineno"> 6127</span>&#160;</div><div class="line"><a name="l06128"></a><span class="lineno"> 6128</span>&#160;- `void soap_print_fault(struct soap*, FILE *fd)` prints the error message to a</div><div class="line"><a name="l06129"></a><span class="lineno"> 6129</span>&#160;  FILE descriptor.</div><div class="line"><a name="l06130"></a><span class="lineno"> 6130</span>&#160;</div><div class="line"><a name="l06131"></a><span class="lineno"> 6131</span>&#160;- `void soap_sprint_fault(struct soap*, char *buf, size_t len)` saves the error</div><div class="line"><a name="l06132"></a><span class="lineno"> 6132</span>&#160;  message to a fixed-size buffer allocated with a maximum length.</div><div class="line"><a name="l06133"></a><span class="lineno"> 6133</span>&#160;</div><div class="line"><a name="l06134"></a><span class="lineno"> 6134</span>&#160;- `void soap_print_fault_location(struct soap*, FILE *fd)` prints the location</div><div class="line"><a name="l06135"></a><span class="lineno"> 6135</span>&#160;  and part of the XML where the parser encountered an error.</div><div class="line"><a name="l06136"></a><span class="lineno"> 6136</span>&#160;</div><div class="line"><a name="l06137"></a><span class="lineno"> 6137</span>&#160;C++ exceptions are never raised by the engine or serializers, even when data is</div><div class="line"><a name="l06138"></a><span class="lineno"> 6138</span>&#160;allocated.</div><div class="line"><a name="l06139"></a><span class="lineno"> 6139</span>&#160;</div><div class="line"><a name="l06140"></a><span class="lineno"> 6140</span>&#160;A `SOAP_EOM` error code is returned when memory was exhausted during</div><div class="line"><a name="l06141"></a><span class="lineno"> 6141</span>&#160;processing of input and/or output of data.</div><div class="line"><a name="l06142"></a><span class="lineno"> 6142</span>&#160;</div><div class="line"><a name="l06143"></a><span class="lineno"> 6143</span>&#160;An EOF (`SOAP_EOF` or -1) error code is returned when the parser has hit EOF</div><div class="line"><a name="l06144"></a><span class="lineno"> 6144</span>&#160;but expected more input, or when socket communications timed out.  In addition</div><div class="line"><a name="l06145"></a><span class="lineno"> 6145</span>&#160;to the `SOAP_EOF` error, the `int soap::errnum` of the `soap` context is</div><div class="line"><a name="l06146"></a><span class="lineno"> 6146</span>&#160;set to the `errno` value of the operation that failed.  For timeouts, the</div><div class="line"><a name="l06147"></a><span class="lineno"> 6147</span>&#160;`soap::ernum` value is always 0 instead of an `errno` error code.</div><div class="line"><a name="l06148"></a><span class="lineno"> 6148</span>&#160;</div><div class="line"><a name="l06149"></a><span class="lineno"> 6149</span>&#160;Use `soap_xml_error_check(soap-&gt;error)` to check for XML errors.  This returns</div><div class="line"><a name="l06150"></a><span class="lineno"> 6150</span>&#160;true (non-zero) when a parsing and validation error has occurred.</div><div class="line"><a name="l06151"></a><span class="lineno"> 6151</span>&#160;</div><div class="line"><a name="l06152"></a><span class="lineno"> 6152</span>&#160;For example:</div><div class="line"><a name="l06153"></a><span class="lineno"> 6153</span>&#160;</div><div class="line"><a name="l06154"></a><span class="lineno"> 6154</span>&#160;~~~{.cpp}</div><div class="line"><a name="l06155"></a><span class="lineno"> 6155</span>&#160;    #include &lt;sstream&gt;</div><div class="line"><a name="l06156"></a><span class="lineno"> 6156</span>&#160;</div><div class="line"><a name="l06157"></a><span class="lineno"> 6157</span>&#160;    struct soap *soap = soap_new1(SOAP_XML_INDENT | SOAP_XML_STRICT | SOAP_XML_TREE);</div><div class="line"><a name="l06158"></a><span class="lineno"> 6158</span>&#160;    struct ns__record person;</div><div class="line"><a name="l06159"></a><span class="lineno"> 6159</span>&#160;    std::stringstream ss;</div><div class="line"><a name="l06160"></a><span class="lineno"> 6160</span>&#160;    ss.str(&quot;...&quot;);      // XML to parse</div><div class="line"><a name="l06161"></a><span class="lineno"> 6161</span>&#160;    soap-&gt;is = &amp;ss;</div><div class="line"><a name="l06162"></a><span class="lineno"> 6162</span>&#160;    if (soap_read__ns__record(soap, &amp;person))</div><div class="line"><a name="l06163"></a><span class="lineno"> 6163</span>&#160;    {</div><div class="line"><a name="l06164"></a><span class="lineno"> 6164</span>&#160;      if (soap_xml_error_check(soap-&gt;error))</div><div class="line"><a name="l06165"></a><span class="lineno"> 6165</span>&#160;        std::cerr &lt;&lt; &quot;XML parsing error!&quot; &lt;&lt; std::endl;</div><div class="line"><a name="l06166"></a><span class="lineno"> 6166</span>&#160;      else</div><div class="line"><a name="l06167"></a><span class="lineno"> 6167</span>&#160;        soap_stream_fault(soap, std::cerr);</div><div class="line"><a name="l06168"></a><span class="lineno"> 6168</span>&#160;    }</div><div class="line"><a name="l06169"></a><span class="lineno"> 6169</span>&#160;    else</div><div class="line"><a name="l06170"></a><span class="lineno"> 6170</span>&#160;    {</div><div class="line"><a name="l06171"></a><span class="lineno"> 6171</span>&#160;      ...               // all OK, use person record</div><div class="line"><a name="l06172"></a><span class="lineno"> 6172</span>&#160;    }</div><div class="line"><a name="l06173"></a><span class="lineno"> 6173</span>&#160;    soap_destroy(soap); // delete objects</div><div class="line"><a name="l06174"></a><span class="lineno"> 6174</span>&#160;    soap_end(soap);     // delete other data and temp data</div><div class="line"><a name="l06175"></a><span class="lineno"> 6175</span>&#160;    soap_free(soap);    // free context</div><div class="line"><a name="l06176"></a><span class="lineno"> 6176</span>&#160;~~~</div><div class="line"><a name="l06177"></a><span class="lineno"> 6177</span>&#160;</div><div class="line"><a name="l06178"></a><span class="lineno"> 6178</span>&#160;When deploying your application on UNIX and Linux systems, UNIX signal handlers</div><div class="line"><a name="l06179"></a><span class="lineno"> 6179</span>&#160;should be added to your code handle signals, in particular `SIGPIPE`:</div><div class="line"><a name="l06180"></a><span class="lineno"> 6180</span>&#160;</div><div class="line"><a name="l06181"></a><span class="lineno"> 6181</span>&#160;~~~{.cpp}</div><div class="line"><a name="l06182"></a><span class="lineno"> 6182</span>&#160;    signal(SIGPIPE, sigpipe_handler);</div><div class="line"><a name="l06183"></a><span class="lineno"> 6183</span>&#160;~~~</div><div class="line"><a name="l06184"></a><span class="lineno"> 6184</span>&#160;</div><div class="line"><a name="l06185"></a><span class="lineno"> 6185</span>&#160;where the `sigpipe_handler` is a function:</div><div class="line"><a name="l06186"></a><span class="lineno"> 6186</span>&#160;</div><div class="line"><a name="l06187"></a><span class="lineno"> 6187</span>&#160;~~~{.cpp}</div><div class="line"><a name="l06188"></a><span class="lineno"> 6188</span>&#160;    void sigpipe_handler(int x) { }</div><div class="line"><a name="l06189"></a><span class="lineno"> 6189</span>&#160;~~~</div><div class="line"><a name="l06190"></a><span class="lineno"> 6190</span>&#160;</div><div class="line"><a name="l06191"></a><span class="lineno"> 6191</span>&#160;Other UNIX signals may have to be handled as well.</div><div class="line"><a name="l06192"></a><span class="lineno"> 6192</span>&#160;</div><div class="line"><a name="l06193"></a><span class="lineno"> 6193</span>&#160;The engine is designed for easy memory cleanup after being interrupted.  Use</div><div class="line"><a name="l06194"></a><span class="lineno"> 6194</span>&#160;`soap_destroy(soap)` and `soap_end(soap)`, after which the `soap` context can</div><div class="line"><a name="l06195"></a><span class="lineno"> 6195</span>&#160;be reused.</div><div class="line"><a name="l06196"></a><span class="lineno"> 6196</span>&#160;</div><div class="line"><a name="l06197"></a><span class="lineno"> 6197</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l06198"></a><span class="lineno"> 6198</span>&#160;</div><div class="line"><a name="l06199"></a><span class="lineno"> 6199</span>&#160;Features and limitations                                             {#features}</div><div class="line"><a name="l06200"></a><span class="lineno"> 6200</span>&#160;========================</div><div class="line"><a name="l06201"></a><span class="lineno"> 6201</span>&#160;</div><div class="line"><a name="l06202"></a><span class="lineno"> 6202</span>&#160;In general, to use the generated code:</div><div class="line"><a name="l06203"></a><span class="lineno"> 6203</span>&#160;</div><div class="line"><a name="l06204"></a><span class="lineno"> 6204</span>&#160;- Make sure to `#include &quot;soapH.h&quot;` in your code and also define a namespace</div><div class="line"><a name="l06205"></a><span class="lineno"> 6205</span>&#160;  table or `#include &quot;ns.nsmap&quot;` with the generated table, where `ns` is the</div><div class="line"><a name="l06206"></a><span class="lineno"> 6206</span>&#160;  namespace prefix for services.</div><div class="line"><a name="l06207"></a><span class="lineno"> 6207</span>&#160;</div><div class="line"><a name="l06208"></a><span class="lineno"> 6208</span>&#160;- Use &lt;b&gt;`soapcpp2 -j`&lt;/b&gt; option &lt;b&gt;`-j`&lt;/b&gt; (C++ only) to generate C++ proxy and service objects.</div><div class="line"><a name="l06209"></a><span class="lineno"> 6209</span>&#160;  The auto-generated files include documented inferfaces.  Compile with</div><div class="line"><a name="l06210"></a><span class="lineno"> 6210</span>&#160;  &lt;i&gt;`soapC.cpp`&lt;/i&gt; and link with &lt;b&gt;`-lgsoap++`&lt;/b&gt;, or alternatively compile</div><div class="line"><a name="l06211"></a><span class="lineno"> 6211</span>&#160;  &lt;i&gt;`gsoap/stdsoap2.cpp`&lt;/i&gt;.</div><div class="line"><a name="l06212"></a><span class="lineno"> 6212</span>&#160;</div><div class="line"><a name="l06213"></a><span class="lineno"> 6213</span>&#160;- Without &lt;b&gt;`soapcpp2 -j`&lt;/b&gt; option &lt;b&gt;`-j`&lt;/b&gt;: client-side uses the auto-generated</div><div class="line"><a name="l06214"></a><span class="lineno"> 6214</span>&#160;  &lt;i&gt;`soapClient.cpp`&lt;/i&gt; and &lt;i&gt;`soapC.cpp`&lt;/i&gt; (or C versions of those).</div><div class="line"><a name="l06215"></a><span class="lineno"> 6215</span>&#160;  Compile and link with &lt;b&gt;`-lgsoap++`&lt;/b&gt; (&lt;b&gt;`-lgsoap`&lt;/b&gt; for C), or</div><div class="line"><a name="l06216"></a><span class="lineno"> 6216</span>&#160;  alternatively compile &lt;i&gt;`gsoap/stdsoap2.cpp`&lt;/i&gt; (&lt;i&gt;`gsoap/stdsoap2.c`&lt;/i&gt;</div><div class="line"><a name="l06217"></a><span class="lineno"> 6217</span>&#160;  for C).</div><div class="line"><a name="l06218"></a><span class="lineno"> 6218</span>&#160;</div><div class="line"><a name="l06219"></a><span class="lineno"> 6219</span>&#160;- Without &lt;b&gt;`soapcpp2 -j`&lt;/b&gt; option &lt;b&gt;`-j`&lt;/b&gt;: server-side uses the</div><div class="line"><a name="l06220"></a><span class="lineno"> 6220</span>&#160;  auto-generated &lt;i&gt;`soapServer.cpp`&lt;/i&gt; and &lt;i&gt;`soapC.cpp`&lt;/i&gt; (or C versions</div><div class="line"><a name="l06221"></a><span class="lineno"> 6221</span>&#160;  of those).  Compile and link with &lt;b&gt;`-lgsoap++`&lt;/b&gt; (&lt;b&gt;`-lgsoap`&lt;/b&gt; for</div><div class="line"><a name="l06222"></a><span class="lineno"> 6222</span>&#160;  C), or alternatively compile &lt;i&gt;`gsoap/stdsoap2.cpp`&lt;/i&gt; (&lt;i&gt;`stdsoap2.c`&lt;/i&gt;</div><div class="line"><a name="l06223"></a><span class="lineno"> 6223</span>&#160;  for C).</div><div class="line"><a name="l06224"></a><span class="lineno"> 6224</span>&#160;</div><div class="line"><a name="l06225"></a><span class="lineno"> 6225</span>&#160;- Use `soap_new()` or `soap_new1(int flags)` to allocate and initialize a</div><div class="line"><a name="l06226"></a><span class="lineno"> 6226</span>&#160;  heap-allocated `soap` context with or without flags.  Delete this `soap` context with</div><div class="line"><a name="l06227"></a><span class="lineno"> 6227</span>&#160;  `soap_free(struct soap*)`, but only after `soap_destroy(struct soap*)` and</div><div class="line"><a name="l06228"></a><span class="lineno"> 6228</span>&#160;  `soap_end(struct soap*)`.</div><div class="line"><a name="l06229"></a><span class="lineno"> 6229</span>&#160;</div><div class="line"><a name="l06230"></a><span class="lineno"> 6230</span>&#160;- Use `soap_init(struct *soap)` or `soap_init1(struct soap*, int flags)` to</div><div class="line"><a name="l06231"></a><span class="lineno"> 6231</span>&#160;  initialize a stack-allocated `soap` context with or without flags.  End the use of</div><div class="line"><a name="l06232"></a><span class="lineno"> 6232</span>&#160;  this context with `soap_done(struct soap*)`, but only after</div><div class="line"><a name="l06233"></a><span class="lineno"> 6233</span>&#160;  `soap_destroy(struct soap*)` and `soap_end(struct soap*)`.</div><div class="line"><a name="l06234"></a><span class="lineno"> 6234</span>&#160;</div><div class="line"><a name="l06235"></a><span class="lineno"> 6235</span>&#160;Additional notes with respect to the wsdl2h and soapcpp2 tools:</div><div class="line"><a name="l06236"></a><span class="lineno"> 6236</span>&#160;</div><div class="line"><a name="l06237"></a><span class="lineno"> 6237</span>&#160;- Nested classes, structs, and unions in a interface header file are unnested</div><div class="line"><a name="l06238"></a><span class="lineno"> 6238</span>&#160;  by soapcpp2.</div><div class="line"><a name="l06239"></a><span class="lineno"> 6239</span>&#160;</div><div class="line"><a name="l06240"></a><span class="lineno"> 6240</span>&#160;- Use `#import &quot;file.h&quot;` instead of `#include` to import other header files in</div><div class="line"><a name="l06241"></a><span class="lineno"> 6241</span>&#160;  a interface header file for soapcpp2.  The `#include`, `#define`, and</div><div class="line"><a name="l06242"></a><span class="lineno"> 6242</span>&#160;  `#pragma` are accepted by soapcpp2, but are moved to the very start of the</div><div class="line"><a name="l06243"></a><span class="lineno"> 6243</span>&#160;  generated code for the C/C++ compiler to include before all generated</div><div class="line"><a name="l06244"></a><span class="lineno"> 6244</span>&#160;  definitions.  Often it is useful to add an `#include` with a</div><div class="line"><a name="l06245"></a><span class="lineno"> 6245</span>&#160;  [volatile type](#toxsd9-2) that includes the actual type declaration, and to</div><div class="line"><a name="l06246"></a><span class="lineno"> 6246</span>&#160;  ensure transient types are declared when these are used in a data binding</div><div class="line"><a name="l06247"></a><span class="lineno"> 6247</span>&#160;  interface declared in a interface header file for soapcpp2.</div><div class="line"><a name="l06248"></a><span class="lineno"> 6248</span>&#160;</div><div class="line"><a name="l06249"></a><span class="lineno"> 6249</span>&#160;- To remove any SOAP-specific bindings, use &lt;b&gt;`soapcpp2 -0`&lt;/b&gt; option &lt;b&gt;`-0`&lt;/b&gt;.</div><div class="line"><a name="l06250"></a><span class="lineno"> 6250</span>&#160;</div><div class="line"><a name="l06251"></a><span class="lineno"> 6251</span>&#160;- A interface header file for soapcpp2 should not include any code statements,</div><div class="line"><a name="l06252"></a><span class="lineno"> 6252</span>&#160;  only data type declarations.  This includes constructor initialization lists</div><div class="line"><a name="l06253"></a><span class="lineno"> 6253</span>&#160;  that are not permitted.  Use member initializations instead.</div><div class="line"><a name="l06254"></a><span class="lineno"> 6254</span>&#160;</div><div class="line"><a name="l06255"></a><span class="lineno"> 6255</span>&#160;- C++ namespaces are supported.  Use &lt;b&gt;`wsdl2h -qname`&lt;/b&gt; option</div><div class="line"><a name="l06256"></a><span class="lineno"> 6256</span>&#160;  &lt;b&gt;`-qname`&lt;/b&gt; to add C++ namespace `name`.  Or add a `namespace name { ... }`</div><div class="line"><a name="l06257"></a><span class="lineno"> 6257</span>&#160;  to the header file, but the `{ ... }` must cover the entire</div><div class="line"><a name="l06258"></a><span class="lineno"> 6258</span>&#160;  header file content from begin to end.</div><div class="line"><a name="l06259"></a><span class="lineno"> 6259</span>&#160;  </div><div class="line"><a name="l06260"></a><span class="lineno"> 6260</span>&#160;- Optional XML DOM support can be used to store mixed content or literal XML</div><div class="line"><a name="l06261"></a><span class="lineno"> 6261</span>&#160;  content.  Otherwise, mixed content may be lost.  Use &lt;b&gt;`wsdl2h -d`&lt;/b&gt;</div><div class="line"><a name="l06262"></a><span class="lineno"> 6262</span>&#160;  option &lt;b&gt;`-d`&lt;/b&gt; for XML DOM support and compile and link with</div><div class="line"><a name="l06263"></a><span class="lineno"> 6263</span>&#160;  &lt;i&gt;`gsoap/dom.c`&lt;/i&gt; or &lt;i&gt;`gsoap/dom.cpp`&lt;/i&gt;.  For details,</div><div class="line"><a name="l06264"></a><span class="lineno"> 6264</span>&#160;  see [XML DOM and XPath](http://www.genivia.com/doc/dom/html).</div><div class="line"><a name="l06265"></a><span class="lineno"> 6265</span>&#160;</div><div class="line"><a name="l06266"></a><span class="lineno"> 6266</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l06267"></a><span class="lineno"> 6267</span>&#160;</div><div class="line"><a name="l06268"></a><span class="lineno"> 6268</span>&#160;Removing SOAP namespaces from XML payloads                              {#nsmap}</div><div class="line"><a name="l06269"></a><span class="lineno"> 6269</span>&#160;==========================================</div><div class="line"><a name="l06270"></a><span class="lineno"> 6270</span>&#160;</div><div class="line"><a name="l06271"></a><span class="lineno"> 6271</span>&#160;The soapcpp2 tool generates a &lt;i&gt;`.nsmap`&lt;/i&gt; file that includes two bindings for SOAP</div><div class="line"><a name="l06272"></a><span class="lineno"> 6272</span>&#160;namespaces.  We can remove all SOAP namespaces (and SOAP processing logic) with</div><div class="line"><a name="l06273"></a><span class="lineno"> 6273</span>&#160;&lt;b&gt;`soapcpp2 -0`&lt;/b&gt; option &lt;b&gt;`-0`&lt;/b&gt; or by simply setting the two entries to NULL:</div><div class="line"><a name="l06274"></a><span class="lineno"> 6274</span>&#160;</div><div class="line"><a name="l06275"></a><span class="lineno"> 6275</span>&#160;~~~{.cpp}</div><div class="line"><a name="l06276"></a><span class="lineno"> 6276</span>&#160;    struct Namespace namespaces[] =</div><div class="line"><a name="l06277"></a><span class="lineno"> 6277</span>&#160;    {</div><div class="line"><a name="l06278"></a><span class="lineno"> 6278</span>&#160;      {&quot;SOAP-ENV&quot;, NULL, NULL, NULL},</div><div class="line"><a name="l06279"></a><span class="lineno"> 6279</span>&#160;      {&quot;SOAP-ENC&quot;, NULL, NULL, NULL},</div><div class="line"><a name="l06280"></a><span class="lineno"> 6280</span>&#160;      ...</div><div class="line"><a name="l06281"></a><span class="lineno"> 6281</span>&#160;    };</div><div class="line"><a name="l06282"></a><span class="lineno"> 6282</span>&#160;~~~</div><div class="line"><a name="l06283"></a><span class="lineno"> 6283</span>&#160;</div><div class="line"><a name="l06284"></a><span class="lineno"> 6284</span>&#160;Once the &lt;i&gt;`.nsmap`&lt;/i&gt; is generated, you can copy-paste the content into your</div><div class="line"><a name="l06285"></a><span class="lineno"> 6285</span>&#160;project code.  However, if we rerun wsdl2h on updated WSDL/XSD files or</div><div class="line"><a name="l06286"></a><span class="lineno"> 6286</span>&#160;&lt;i&gt;`typemap.dat`&lt;/i&gt; declarations then we need to use the updated table.</div><div class="line"><a name="l06287"></a><span class="lineno"> 6287</span>&#160;</div><div class="line"><a name="l06288"></a><span class="lineno"> 6288</span>&#160;In cases that no XML namespaces are used at all, for example with</div><div class="line"><a name="l06289"></a><span class="lineno"> 6289</span>&#160;[XML-RPC](http://www.genivia.com/doc/xml-rpc-json/html), you may use an empty</div><div class="line"><a name="l06290"></a><span class="lineno"> 6290</span>&#160;namespace table:</div><div class="line"><a name="l06291"></a><span class="lineno"> 6291</span>&#160;</div><div class="line"><a name="l06292"></a><span class="lineno"> 6292</span>&#160;~~~{.cpp}</div><div class="line"><a name="l06293"></a><span class="lineno"> 6293</span>&#160;    struct Namespace namespaces[] = {{NULL,NULL,NULL,NULL}};</div><div class="line"><a name="l06294"></a><span class="lineno"> 6294</span>&#160;~~~</div><div class="line"><a name="l06295"></a><span class="lineno"> 6295</span>&#160;</div><div class="line"><a name="l06296"></a><span class="lineno"> 6296</span>&#160;However, beware that any built-in xsi attributes that are rendered will lack</div><div class="line"><a name="l06297"></a><span class="lineno"> 6297</span>&#160;the proper namespace binding.  At least we suggest to use `SOAP_XML_NOTYPE` for</div><div class="line"><a name="l06298"></a><span class="lineno"> 6298</span>&#160;this reason.</div><div class="line"><a name="l06299"></a><span class="lineno"> 6299</span>&#160;</div><div class="line"><a name="l06300"></a><span class="lineno"> 6300</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l06301"></a><span class="lineno"> 6301</span>&#160;</div><div class="line"><a name="l06302"></a><span class="lineno"> 6302</span>&#160;Examples                                                             {#examples}</div><div class="line"><a name="l06303"></a><span class="lineno"> 6303</span>&#160;========</div><div class="line"><a name="l06304"></a><span class="lineno"> 6304</span>&#160;</div><div class="line"><a name="l06305"></a><span class="lineno"> 6305</span>&#160;Select the project files below to peruse the source code examples.</div><div class="line"><a name="l06306"></a><span class="lineno"> 6306</span>&#160;</div><div class="line"><a name="l06307"></a><span class="lineno"> 6307</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l06308"></a><span class="lineno"> 6308</span>&#160;</div><div class="line"><a name="l06309"></a><span class="lineno"> 6309</span>&#160;Source files</div><div class="line"><a name="l06310"></a><span class="lineno"> 6310</span>&#160;------------</div><div class="line"><a name="l06311"></a><span class="lineno"> 6311</span>&#160;</div><div class="line"><a name="l06312"></a><span class="lineno"> 6312</span>&#160;- &lt;i&gt;`address.xsd`&lt;/i&gt;         Address book schema</div><div class="line"><a name="l06313"></a><span class="lineno"> 6313</span>&#160;- &lt;i&gt;`address.cpp`&lt;/i&gt;         Address book app (reads/writes address.xml file)</div><div class="line"><a name="l06314"></a><span class="lineno"> 6314</span>&#160;- &lt;i&gt;`addresstypemap.dat`&lt;/i&gt;  Schema namespace prefix name preference for wsdl2h</div><div class="line"><a name="l06315"></a><span class="lineno"> 6315</span>&#160;- &lt;i&gt;`graph.h`&lt;/i&gt;             Graph data binding (tree, digraph, cyclic graph)</div><div class="line"><a name="l06316"></a><span class="lineno"> 6316</span>&#160;- &lt;i&gt;`graph.cpp`&lt;/i&gt;           Test graph serialization as tree, digraph, and cyclic</div><div class="line"><a name="l06317"></a><span class="lineno"> 6317</span>&#160;</div><div class="line"><a name="l06318"></a><span class="lineno"> 6318</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l06319"></a><span class="lineno"> 6319</span>&#160;</div><div class="line"><a name="l06320"></a><span class="lineno"> 6320</span>&#160;Generated files</div><div class="line"><a name="l06321"></a><span class="lineno"> 6321</span>&#160;---------------</div><div class="line"><a name="l06322"></a><span class="lineno"> 6322</span>&#160;</div><div class="line"><a name="l06323"></a><span class="lineno"> 6323</span>&#160;- &lt;i&gt;`address.h`&lt;/i&gt;      data binding interface generated from address.xsd</div><div class="line"><a name="l06324"></a><span class="lineno"> 6324</span>&#160;- &lt;i&gt;`addressStub.h`&lt;/i&gt;  C++ data binding definitions</div><div class="line"><a name="l06325"></a><span class="lineno"> 6325</span>&#160;- &lt;i&gt;`addressH.h`&lt;/i&gt;     Serializers</div><div class="line"><a name="l06326"></a><span class="lineno"> 6326</span>&#160;- &lt;i&gt;`addressC.cpp`&lt;/i&gt;   Serializers</div><div class="line"><a name="l06327"></a><span class="lineno"> 6327</span>&#160;- &lt;i&gt;`address.xml`&lt;/i&gt;    Address book data generated by address app</div><div class="line"><a name="l06328"></a><span class="lineno"> 6328</span>&#160;- &lt;i&gt;`graphStub.h`&lt;/i&gt;    C++ data binding definitions</div><div class="line"><a name="l06329"></a><span class="lineno"> 6329</span>&#160;- &lt;i&gt;`graphH.h`&lt;/i&gt;       Serializers</div><div class="line"><a name="l06330"></a><span class="lineno"> 6330</span>&#160;- &lt;i&gt;`graphC.cpp`&lt;/i&gt;     Serializers</div><div class="line"><a name="l06331"></a><span class="lineno"> 6331</span>&#160;- &lt;i&gt;`g.xsd`&lt;/i&gt;          XSD schema with &lt;i&gt;`g:Graph`&lt;/i&gt; complexType</div><div class="line"><a name="l06332"></a><span class="lineno"> 6332</span>&#160;- &lt;i&gt;`g.nsmap`&lt;/i&gt;        xmlns bindings namespace mapping table</div><div class="line"><a name="l06333"></a><span class="lineno"> 6333</span>&#160;</div><div class="line"><a name="l06334"></a><span class="lineno"> 6334</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l06335"></a><span class="lineno"> 6335</span>&#160;</div><div class="line"><a name="l06336"></a><span class="lineno"> 6336</span>&#160;Build steps</div><div class="line"><a name="l06337"></a><span class="lineno"> 6337</span>&#160;-----------</div><div class="line"><a name="l06338"></a><span class="lineno"> 6338</span>&#160;</div><div class="line"><a name="l06339"></a><span class="lineno"> 6339</span>&#160;Building the AddressBook example:</div><div class="line"><a name="l06340"></a><span class="lineno"> 6340</span>&#160;</div><div class="line"><a name="l06341"></a><span class="lineno"> 6341</span>&#160;    wsdl2h -g -taddresstypemap.dat address.xsd</div><div class="line"><a name="l06342"></a><span class="lineno"> 6342</span>&#160;    soapcpp2 -0 -C -S -paddress -I../../import address.h</div><div class="line"><a name="l06343"></a><span class="lineno"> 6343</span>&#160;    c++ -I../.. address.cpp addressC.cpp -o address -lgsoap++</div><div class="line"><a name="l06344"></a><span class="lineno"> 6344</span>&#160;</div><div class="line"><a name="l06345"></a><span class="lineno"> 6345</span>&#160;Using &lt;b&gt;`wsdl2h -g -taddresstypemap.dat`&lt;/b&gt; option &lt;b&gt;`-g`&lt;/b&gt; produces</div><div class="line"><a name="l06346"></a><span class="lineno"> 6346</span>&#160;bindings for global (root) elements in addition to types and option</div><div class="line"><a name="l06347"></a><span class="lineno"> 6347</span>&#160;&lt;b&gt;`-taddresstypemap.dat`&lt;/b&gt; specifies a mapping file, see further below.</div><div class="line"><a name="l06348"></a><span class="lineno"> 6348</span>&#160;</div><div class="line"><a name="l06349"></a><span class="lineno"> 6349</span>&#160;In this case the root element &lt;i&gt;`a:address-book`&lt;/i&gt; is bound to `_a__address_book`.</div><div class="line"><a name="l06350"></a><span class="lineno"> 6350</span>&#160;The complexType &lt;i&gt;`a:address`&lt;/i&gt; is bound to class `a__address`, which is also the</div><div class="line"><a name="l06351"></a><span class="lineno"> 6351</span>&#160;type of `_a__address_book`.  This option is not required, but allows you to use</div><div class="line"><a name="l06352"></a><span class="lineno"> 6352</span>&#160;global element tag names when referring to their serializers, instead of their</div><div class="line"><a name="l06353"></a><span class="lineno"> 6353</span>&#160;type name.  Using &lt;b&gt;`soapcpp2 -0 -C -S -paddress`&lt;/b&gt; option &lt;b&gt;`-0`&lt;/b&gt; removes the</div><div class="line"><a name="l06354"></a><span class="lineno"> 6354</span>&#160;SOAP protocol and the combination of the two options &lt;b&gt;`-C`&lt;/b&gt; and</div><div class="line"><a name="l06355"></a><span class="lineno"> 6355</span>&#160;&lt;b&gt;`-S`&lt;/b&gt; removes client and server code generation (using option &lt;b&gt;`-C`&lt;/b&gt;</div><div class="line"><a name="l06356"></a><span class="lineno"> 6356</span>&#160;alone generates client code and using option &lt;b&gt;`-S`&lt;/b&gt; alone generates server</div><div class="line"><a name="l06357"></a><span class="lineno"> 6357</span>&#160;code).  Option &lt;b&gt;`-paddress`&lt;/b&gt; renames the output &lt;i&gt;`soap`&lt;/i&gt;-prefixed files to</div><div class="line"><a name="l06358"></a><span class="lineno"> 6358</span>&#160;&lt;i&gt;`address`&lt;/i&gt;-prefixed files.</div><div class="line"><a name="l06359"></a><span class="lineno"> 6359</span>&#160;</div><div class="line"><a name="l06360"></a><span class="lineno"> 6360</span>&#160;See the &lt;i&gt;`address.cpp`&lt;/i&gt; implementation and [related pages](pages.html).</div><div class="line"><a name="l06361"></a><span class="lineno"> 6361</span>&#160;</div><div class="line"><a name="l06362"></a><span class="lineno"> 6362</span>&#160;The &lt;i&gt;`addresstypemap.dat`&lt;/i&gt; file specifies the XML namespace prefix for the</div><div class="line"><a name="l06363"></a><span class="lineno"> 6363</span>&#160;bindings:</div><div class="line"><a name="l06364"></a><span class="lineno"> 6364</span>&#160;</div><div class="line"><a name="l06365"></a><span class="lineno"> 6365</span>&#160;    #       Bind the address book schema namespace to prefix &#39;a&#39;</div><div class="line"><a name="l06366"></a><span class="lineno"> 6366</span>&#160;</div><div class="line"><a name="l06367"></a><span class="lineno"> 6367</span>&#160;    a = &quot;urn:address-book-example&quot;</div><div class="line"><a name="l06368"></a><span class="lineno"> 6368</span>&#160;</div><div class="line"><a name="l06369"></a><span class="lineno"> 6369</span>&#160;    #       By default the xsd:dateTime schema type is translated to time_t</div><div class="line"><a name="l06370"></a><span class="lineno"> 6370</span>&#160;    #       To map xsd:dateTime to struct tm, enable the following line:</div><div class="line"><a name="l06371"></a><span class="lineno"> 6371</span>&#160;</div><div class="line"><a name="l06372"></a><span class="lineno"> 6372</span>&#160;    # xsd__dateTime = #import &quot;../../custom/struct_tm.h&quot;</div><div class="line"><a name="l06373"></a><span class="lineno"> 6373</span>&#160;</div><div class="line"><a name="l06374"></a><span class="lineno"> 6374</span>&#160;    #       ... and compile/link with custom/struct_tm.c</div><div class="line"><a name="l06375"></a><span class="lineno"> 6375</span>&#160;</div><div class="line"><a name="l06376"></a><span class="lineno"> 6376</span>&#160;The DOB field is a &lt;i&gt;`xsd:dateTime`&lt;/i&gt;, which is bound to `time_t` by default.  To</div><div class="line"><a name="l06377"></a><span class="lineno"> 6377</span>&#160;change this to `struct tm`, enable the import of the `xsd__dateTime` custom</div><div class="line"><a name="l06378"></a><span class="lineno"> 6378</span>&#160;serializer by uncommenting the definition of `xsd__dateTime` in</div><div class="line"><a name="l06379"></a><span class="lineno"> 6379</span>&#160;&lt;i&gt;`addresstypemap.dat`&lt;/i&gt;.  Then change `soap_dateTime2s` to `soap_xsd__dateTime2s`</div><div class="line"><a name="l06380"></a><span class="lineno"> 6380</span>&#160;in the code.</div><div class="line"><a name="l06381"></a><span class="lineno"> 6381</span>&#160;</div><div class="line"><a name="l06382"></a><span class="lineno"> 6382</span>&#160;Building the graph serialization example:</div><div class="line"><a name="l06383"></a><span class="lineno"> 6383</span>&#160;</div><div class="line"><a name="l06384"></a><span class="lineno"> 6384</span>&#160;    soapcpp2 -C -S -pgraph -I../../import graph.h</div><div class="line"><a name="l06385"></a><span class="lineno"> 6385</span>&#160;    c++ -I../.. graph.cpp graphC.cpp -o graph -lgsoap++</div><div class="line"><a name="l06386"></a><span class="lineno"> 6386</span>&#160;</div><div class="line"><a name="l06387"></a><span class="lineno"> 6387</span>&#160;To compile without using the &lt;b&gt;`-lgsoap++`&lt;/b&gt; library: simply compile</div><div class="line"><a name="l06388"></a><span class="lineno"> 6388</span>&#160;&lt;i&gt;`stdsoap2.cpp`&lt;/i&gt; together with the above.</div><div class="line"><a name="l06389"></a><span class="lineno"> 6389</span>&#160;</div><div class="line"><a name="l06390"></a><span class="lineno"> 6390</span>&#160;🔝 [Back to table of contents](#)</div><div class="line"><a name="l06391"></a><span class="lineno"> 6391</span>&#160;</div><div class="line"><a name="l06392"></a><span class="lineno"> 6392</span>&#160;Usage</div><div class="line"><a name="l06393"></a><span class="lineno"> 6393</span>&#160;-----</div><div class="line"><a name="l06394"></a><span class="lineno"> 6394</span>&#160;</div><div class="line"><a name="l06395"></a><span class="lineno"> 6395</span>&#160;To execute the AddressBook example:</div><div class="line"><a name="l06396"></a><span class="lineno"> 6396</span>&#160;</div><div class="line"><a name="l06397"></a><span class="lineno"> 6397</span>&#160;    ./address</div><div class="line"><a name="l06398"></a><span class="lineno"> 6398</span>&#160;</div><div class="line"><a name="l06399"></a><span class="lineno"> 6399</span>&#160;To execute the Graph serialization example:</div><div class="line"><a name="l06400"></a><span class="lineno"> 6400</span>&#160;</div><div class="line"><a name="l06401"></a><span class="lineno"> 6401</span>&#160;    ./graph</div><div class="line"><a name="l06402"></a><span class="lineno"> 6402</span>&#160;</div></div><!-- fragment --></div><!-- contents -->
</div><!-- doc-content -->
<hr class="footer">
<address class="footer">
Copyright (C) 2022, Robert van Engelen, Genivia Inc., All Rights Reserved.
</address>
<address class="footer"><small>
Converted on Sun Dec 4 2022 15:33:33 by <a target="_blank" href="http://www.doxygen.org/index.html">Doxygen</a> 1.8.11</small></address>
<br>
<div style="height: 246px; background: #DBDBDB;">
</body>
</html>
